Merge work by John Scipione on the Haiku Book.
* Some new classes documented * Screenshots for the interface kit controls * A lot of typo fixes * Some css tweaks This has some backporting to the current version of Doxygen, since there are experiments to get coloring similar to the one in the Be Book that will hopefully be upstreamed in Doxygen. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42608 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Adrien Destugues
@@ -16,15 +16,13 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\file Archivable.h
|
||||
/*! \file Archivable.h
|
||||
\brief Provides the BArchivable interface and declares the BArchiver and
|
||||
BUnarchiver classes.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\class BArchivable
|
||||
/*! \class BArchivable
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief Interface for objects that can be archived into a BMessage.
|
||||
@@ -65,8 +63,7 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BArchivable::BArchivable(BMessage* from)
|
||||
/*! \fn BArchivable::BArchivable(BMessage* from)
|
||||
\brief Constructor. Does important behind-the-scenes work in the unarchiving
|
||||
process.
|
||||
|
||||
@@ -77,20 +74,17 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BArchivable::BArchivable()
|
||||
/*! \fn BArchivable::BArchivable()
|
||||
\brief Constructor. Does nothing.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BArchivable::~BArchivable()
|
||||
/*! \fn BArchivable::~BArchivable()
|
||||
\brief Destructor. Does nothing.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BArchivable::Archive(BMessage* into,
|
||||
/*! \fn virtual status_t BArchivable::Archive(BMessage* into,
|
||||
bool deep = true) const
|
||||
\brief Archive the object into a BMessage.
|
||||
|
||||
@@ -105,8 +99,7 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
|
||||
/*! \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
|
||||
\brief Static member to restore objects from messages.
|
||||
|
||||
You should always check that the \a archive argument actually corresponds to
|
||||
@@ -127,17 +120,15 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
|
||||
\brief Internal method.
|
||||
/*! \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
|
||||
\brief Internal method defined for binary compatibility purposes.
|
||||
\internal This method is defined for binary compatibility purposes, it is
|
||||
used to ensure that the correct AllUnarchived() and AllArchived()
|
||||
methods are called for objects, as those methods are new to Haiku.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
|
||||
/*! \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
|
||||
\brief Method relating to the use of \c BUnarchiver.
|
||||
|
||||
This hook function is called triggered in the BUnarchiver::Finish() method.
|
||||
@@ -146,32 +137,31 @@
|
||||
Implementations of this method should call the implementation of
|
||||
their parent class, the same as for the Archive() method.
|
||||
|
||||
\note To guarantee that your AllUnarchived() method will be called during
|
||||
unarchival, you must create a BUnarchiver object in your archive
|
||||
constructor.
|
||||
\warning To guarantee that your AllUnarchived() method will be called
|
||||
during unarchival, you must create a BUnarchiver object in your
|
||||
archive constructor.
|
||||
|
||||
\see BUnarchiver, BUnarchiver::Finish()
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn virtual status_t BArchivable::AllArchived(BMessage* into) const
|
||||
/*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const
|
||||
\brief Method relating to the use of \c BArchiver.
|
||||
|
||||
This hook function is called once the first BArchiver that was created in
|
||||
an archiving session is either destroyed, or has its \c Finish() method
|
||||
an archiving session is either destroyed, or has its Finish() method
|
||||
called. Implementations of this method can be used, in conjunction with
|
||||
BArchiver::IsArchived(), to reference objects in your archive that you
|
||||
do not own, depending on whether or not those objects were archived by their
|
||||
owners. Implementations of this method should call the implementation of
|
||||
their parent class, the same as for the Archive() method.
|
||||
|
||||
\note To guarantee that your AllArchived() method will be called during
|
||||
archival, you must create a BArchiver object in your Archive()
|
||||
implementation.
|
||||
\warning To guarantee that your AllArchived() method will be called
|
||||
during archival, you must create a BArchiver object in your
|
||||
Archive() implementation.
|
||||
|
||||
\note You should archive any objects you own in your Archive() method
|
||||
implementation, \b NOT your AllArchived() method.
|
||||
\warning You should archive any objects you own in your Archive()
|
||||
method implementation, and \b NOT your AllArchived() method.
|
||||
|
||||
\see BArchiver BArchiver::Finish()
|
||||
*/
|
||||
@@ -184,15 +174,13 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
|
||||
/*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
|
||||
\brief Internal definition of a function that can instantiate objects that
|
||||
have been created with the BArchivable API.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BArchivable* instantiate_object(BMessage *from, image_id *id)
|
||||
/*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
|
||||
\brief Instantiate an archived object with the object being defined in a
|
||||
different application or library.
|
||||
|
||||
@@ -206,8 +194,7 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BArchivable* instantiate_object(BMessage *from)
|
||||
/*! \fn BArchivable* instantiate_object(BMessage *from)
|
||||
\brief Instantiate an archived object.
|
||||
|
||||
This global function will determine the base class, based on the \a from
|
||||
@@ -222,30 +209,26 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool validate_instantiation(BMessage* from, const char* className)
|
||||
/*! \fn bool validate_instantiation(BMessage* from, const char* className)
|
||||
\brief Internal function that checks if the \a className is the same as the
|
||||
one stored in the \a from message.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn instantiation_func find_instantiation_func(const char* className,
|
||||
/*! \fn instantiation_func find_instantiation_func(const char* className,
|
||||
const char* signature)
|
||||
\brief Internal function that searches for the instantiation func with a
|
||||
specific signature. Use instantiate_object() instead.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn instantiation_func find_instantiation_func(const char* className)
|
||||
/*! \fn instantiation_func find_instantiation_func(const char* className)
|
||||
\brief Internal function that searches for the instantiation func of a
|
||||
specific class. Use instantiate_object() instead.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn instantiation_func find_instantiation_func(BMessage* archive)
|
||||
/*! \fn instantiation_func find_instantiation_func(BMessage* archive)
|
||||
\brief Internal function that searches for the instantiation func that
|
||||
works on the specified \a archive. Use instantiate_object() instead.
|
||||
*/
|
||||
|
||||
+20
-23
@@ -13,7 +13,7 @@
|
||||
///// and not completely implemented, so this needs revision if everything
|
||||
///// is finished.
|
||||
|
||||
/*!
|
||||
/*!
|
||||
\file Beep.h
|
||||
\brief Functions to generate sounds from the computer.
|
||||
*/
|
||||
@@ -24,34 +24,31 @@
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn status_t beep()
|
||||
\brief Invoke the standard system beep to alert users.
|
||||
/*! \fn status_t beep()
|
||||
\brief Invoke the standard system beep to alert users.
|
||||
|
||||
From Beep.h and in libbe.so.
|
||||
|
||||
\see system_beep() and add_system_beep_event()
|
||||
From Beep.h and in libbe.so.
|
||||
|
||||
\see system_beep() and add_system_beep_event()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn status_t system_beep(const char* eventName)
|
||||
\brief Invokes the sound for event \a eventName.
|
||||
|
||||
You can add the events using add_system_beep_event().
|
||||
/*! \fn status_t system_beep(const char* eventName)
|
||||
\brief Invokes the sound for event \a eventName.
|
||||
|
||||
From Beep.h and in libbe.so.
|
||||
You can add the events using add_system_beep_event().
|
||||
|
||||
From Beep.h and in libbe.so.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
|
||||
\brief Adds an event to the media server.
|
||||
|
||||
Call this method to add a specific event to the media server.
|
||||
/*! \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
|
||||
\brief Adds an event to the media server.
|
||||
|
||||
From Beep.h and in libbe.so.
|
||||
|
||||
\param eventName The name of the event.
|
||||
\param flags Currently unused. Pass \c 0.
|
||||
Call this method to add a specific event to the media server.
|
||||
|
||||
From Beep.h and in libbe.so.
|
||||
|
||||
\param eventName The name of the event.
|
||||
\param flags Currently unused. Pass \c 0.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
//! @}
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
\class BList
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief An ordered container that is designed to hold generic \c void *
|
||||
\brief An ordered container that is designed to hold generic \c void*
|
||||
objects.
|
||||
|
||||
This class is designed to be used for a variety of tasks. Unlike similar
|
||||
@@ -399,7 +399,7 @@ A C D E F G B H I J
|
||||
If one of the actions on the items fails it means that the \a func function
|
||||
returned \c false and the processing of the list will be stopped.
|
||||
|
||||
\param func A function that takes a \c void * argument and returns a
|
||||
\param func A function that takes a \c void* argument and returns a
|
||||
boolean.
|
||||
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
|
||||
*/
|
||||
@@ -412,8 +412,8 @@ A C D E F G B H I J
|
||||
If one of the actions on the items fails it means that the \a func function
|
||||
returned \c false and the processing of the list will be stopped.
|
||||
|
||||
\param func A function with the first \c void * argument being the item
|
||||
and the second \c void * being the argument that you supply. It should
|
||||
\param func A function with the first \c void* argument being the item
|
||||
and the second \c void* being the argument that you supply. It should
|
||||
return a boolean value on whether it succeeded or not.
|
||||
\param arg2 An argument to supply to \a func.
|
||||
\see DoForEach(bool (*func)(void* item))
|
||||
|
||||
+117
-135
@@ -21,7 +21,7 @@
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int8 int8
|
||||
\typedef typedef __haiku_int8 int8
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -29,7 +29,7 @@
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int16 int16
|
||||
\typedef typedef __haiku_int16 int16
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -37,7 +37,7 @@
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int32 int32
|
||||
\typedef typedef __haiku_int32 int32
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -45,7 +45,7 @@
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef __haiku_int64 int64
|
||||
\typedef typedef __haiku_int64 int64
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -137,9 +137,7 @@
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Character Type Formats
|
||||
*/
|
||||
/*! \name Character Type Formats */
|
||||
|
||||
//! @{
|
||||
|
||||
@@ -153,20 +151,18 @@
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\name Descriptive Type Formats
|
||||
*/
|
||||
/*! \name Descriptive Type Formats */
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\typedef typedef int32 status_t
|
||||
\brief Represents one of the status codes defined in Error.h
|
||||
\typedef typedef int32 status_t
|
||||
\brief Represents one of the status codes defined in Error.h
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef int64 bigtime_t
|
||||
\brief Represents time. The unit depends on the context of the function.
|
||||
\typedef typedef int64 bigtime_t
|
||||
\brief Represents time. The unit depends on the context of the function.
|
||||
*/
|
||||
|
||||
/*!
|
||||
@@ -175,23 +171,21 @@
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef uint32 type_code
|
||||
\brief Represents a certain type of data. See TypeConstants.h for possible
|
||||
values.
|
||||
\typedef typedef uint32 type_code
|
||||
\brief Represents a certain type of data. See TypeConstants.h for
|
||||
possible values.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\typedef typedef uint32 perform_code
|
||||
\brief Unused. Defined by Be to support 'hidden' commands or
|
||||
extensions to classes. The Haiku API has none of these.
|
||||
\typedef typedef uint32 perform_code
|
||||
\brief Unused. Defined by Be to support 'hidden' commands or
|
||||
extensions to classes. The Haiku API has none of these.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Format strings for printf()/scanf()
|
||||
*/
|
||||
/*! \name Format strings for printf()/scanf() */
|
||||
|
||||
//! @{
|
||||
|
||||
@@ -374,9 +368,7 @@
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Format strings for several standard types
|
||||
*/
|
||||
/*! \name Format strings for several standard types */
|
||||
|
||||
//! @{
|
||||
|
||||
@@ -474,41 +466,35 @@
|
||||
|
||||
//////////////// Odds and ends
|
||||
|
||||
/*!
|
||||
\var const char *B_EMPTY_STRING
|
||||
\brief Defines an empty string. Currently defined as the C-string "".
|
||||
/*! \var const char *B_EMPTY_STRING
|
||||
\brief Defines an empty string. Currently defined as the string "".
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def min_c(a,b)
|
||||
\brief Returns the minimum of the values a and b.
|
||||
/*! \def min_c(a,b)
|
||||
\brief Returns the minimum of the values a and b.
|
||||
|
||||
\note When including this header in a C file, use the C equivalent called
|
||||
\c min(a,b).
|
||||
\note When including this header in a C file, use the C equivalent called
|
||||
\c min(a,b).
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def max_c(a,b)
|
||||
\brief Returns the maximum of values a and b.
|
||||
/*! \def max_c(a,b)
|
||||
\brief Returns the maximum of values a and b.
|
||||
|
||||
\note When including this header in a C file, use the C equivalent called
|
||||
\c max(a,b).
|
||||
\note When including this header in a C file, use the C equivalent called
|
||||
\c max(a,b).
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def NULL
|
||||
\brief Defines the constant \c NULL if it hasn't been defined anywhere before.
|
||||
/*! \def NULL
|
||||
\brief Defines the constant \c NULL if it hasn't been defined
|
||||
anywhere before.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\addtogroup support_globals
|
||||
*/
|
||||
/*! \addtogroup support_globals */
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_set(vint32 *value, int32 newValue)
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
/*! \fn int32 atomic_set(vint32 *value, int32 newValue)
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c = \c newValue
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -518,29 +504,28 @@
|
||||
\return The original value of \c value.
|
||||
|
||||
\sa atomic_set64() for a version that works on \c long \c long
|
||||
\sa atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
\sa atomic_test_and_set(), atomic_add(), atomic_and(), atomic_or(),
|
||||
atomic_get()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst)
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
/*! \fn int32 atomic_test_and_set(vint32 *value, int32 newValue,
|
||||
int32 testAgainst)
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
value is \a testAgainst.
|
||||
|
||||
This is a thread-safe way of conditionally performing the \c *value \c +=
|
||||
\c newValue operation. You should use these function when two or more threads
|
||||
might access the variable simultaneously. You don't have to use a semaphore
|
||||
or a mutex in this case.
|
||||
\c newValue operation. You should use these function when two or more
|
||||
threads might access the variable simultaneously. You don't have to use
|
||||
a semaphore or a mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_test_and_set64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_add(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
|
||||
\sa atomic_test_and_set64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_add(), atomic_and(), atomic_or(), atomic_get()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_add(vint32 *value, int32 addValue)
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
/*! \fn int32 atomic_add(vint32 *value, int32 addValue)
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c += \c addValue
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -548,14 +533,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_add64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_and(),
|
||||
atomic_or(), atomic_get()
|
||||
|
||||
\sa atomic_add64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_and(), atomic_or(),
|
||||
atomic_get()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_and(vint32 *value, int32 andValue)
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
/*! \fn int32 atomic_and(vint32 *value, int32 andValue)
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c &= \c andValue
|
||||
@@ -564,15 +549,15 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_and64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(),
|
||||
atomic_or(), atomic_get()
|
||||
|
||||
\sa atomic_and64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_or(),
|
||||
atomic_get()
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_or(vint32 *value, int32 orValue)
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
/*! \fn int32 atomic_or(vint32 *value, int32 orValue)
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c |= \c orValue
|
||||
@@ -581,14 +566,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_or64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_get()
|
||||
|
||||
\sa atomic_or64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_get()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int32 atomic_get(vint32 *value)
|
||||
\brief Atomically return the value of \c value.
|
||||
/*! \fn int32 atomic_get(vint32 *value)
|
||||
\brief Atomically return the value of \c value.
|
||||
|
||||
This is a thread-safe way of reading the contents of the \c value
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -596,14 +581,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_get64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_or()
|
||||
|
||||
\sa atomic_get64() for a version that works on \c long \c long
|
||||
\sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(),
|
||||
atomic_or()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_set64(vint64 *value, int64 newValue)
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
/*! \fn int64 atomic_set64(vint64 *value, int64 newValue)
|
||||
\brief Atomically set the variable \a value to \a newvalue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c = \c newValue
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -612,30 +597,30 @@
|
||||
|
||||
\return The original value of \c value.
|
||||
|
||||
\sa atomic_set() for a version that works on an \c int32
|
||||
\sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
\sa atomic_set() for a version that works on an \c int32
|
||||
\sa atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst)
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
/*! \fn int64 atomic_test_and_set64(vint64 *value, int64 newValue,
|
||||
int64 testAgainst)
|
||||
\brief Atomically set the variable \a value to \a newValue if the current
|
||||
value is \a testAgainst.
|
||||
|
||||
This is a thread-safe way of conditionally performing the \c *value \c +=
|
||||
\c newValue operation. You should use these function when two or more threads
|
||||
might access the variable simultaneously. You don't have to use a semaphore
|
||||
or a mutex in this case.
|
||||
|
||||
This is a thread-safe way of conditionally performing the \c *value
|
||||
\c += \c newValue operation. You should use these function when two
|
||||
or more threads might access the variable simultaneously. You don't
|
||||
have to use a semaphore or a mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_test_and_set() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
|
||||
\sa atomic_test_and_set() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_add64(vint64 *value, int64 addValue)
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
/*! \fn int64 atomic_add64(vint64 *value, int64 addValue)
|
||||
\brief Atomically add the value of \a addValue to \a value.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c += \c addValue
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -643,14 +628,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_add() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
|
||||
\sa atomic_add() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_and64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_and64(vint64 *value, int64 andValue)
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
/*! \fn int64 atomic_and64(vint64 *value, int64 andValue)
|
||||
\brief Atomically perform a bitwise AND operation of \a andValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c &= \c andValue
|
||||
@@ -659,14 +644,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_and() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
|
||||
\sa atomic_and() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
|
||||
atomic_or64(), atomic_get64()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_or64(vint64 *value, int64 orValue)
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
/*! \fn int64 atomic_or64(vint64 *value, int64 orValue)
|
||||
\brief Atomically perform a bitwise OR operation of \a orValue to the
|
||||
variable \a andValue.
|
||||
|
||||
This is a thread-safe way of performing the \c *value \c |= \c orValue
|
||||
@@ -675,14 +660,14 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_or() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_get64()
|
||||
|
||||
\sa atomic_or() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_get64()
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn int64 atomic_get64(vint64 *value)
|
||||
\brief Atomically return the value of \c value.
|
||||
/*! \fn int64 atomic_get64(vint64 *value)
|
||||
\brief Atomically return the value of \c value.
|
||||
|
||||
This is a thread-safe way of reading the contents of the \c value
|
||||
operation. You should use these function when two or more threads might
|
||||
@@ -690,33 +675,30 @@
|
||||
mutex in this case.
|
||||
|
||||
\return The original value of \c value.
|
||||
\sa atomic_get() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(),
|
||||
atomic_or64()
|
||||
|
||||
\sa atomic_get() for a version that works on an \c int32
|
||||
\sa atomic_set64(), atomic_test_and_set64(), atomic_add64(),
|
||||
atomic_and64(), atomic_or64()
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
/*!
|
||||
\fn void* get_stack_frame(void)
|
||||
/*! \fn void* get_stack_frame(void)
|
||||
\brief Internal function.
|
||||
\internal
|
||||
*/
|
||||
|
||||
/*!
|
||||
\name Deprecated defines
|
||||
*/
|
||||
/*! \name Deprecated defines */
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def FALSE
|
||||
\brief Obsolete. Use \c false.
|
||||
/*! \def FALSE
|
||||
\brief Obsolete. Use \c false.
|
||||
*/
|
||||
|
||||
/*!
|
||||
\def TRUE
|
||||
\brief Obsolete. Use \c true.
|
||||
/*! \def TRUE
|
||||
\brief Obsolete. Use \c true.
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
@@ -11,12 +11,11 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\class BUnarchiver
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A class that simplifies the unarchiving of complicated BArchivable
|
||||
hierarchies.
|
||||
/*! \class BUnarchiver
|
||||
\ingroup support
|
||||
\ingroup libbe
|
||||
\brief A class that simplifies the unarchiving of complicated BArchivable
|
||||
hierarchies.
|
||||
|
||||
The BUnarchiver class is a small class used to recover BArchivable objects
|
||||
that have been archived with the BArchiver class. It also provides ownership
|
||||
@@ -40,8 +39,7 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BUnarchiver::BUnarchiver(const BMessage* archive)
|
||||
/*! \fn BUnarchiver::BUnarchiver(const BMessage* archive)
|
||||
\brief Constructs a BUnarchiver object to manage \c archive.
|
||||
|
||||
\note To guarantee that your AllUnarchived() method will be called during
|
||||
@@ -57,74 +55,87 @@
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BUnarchiver::~BUnarchiver()
|
||||
\brief Destroys a BUnarchiver object. Calls this objects Finish() method,
|
||||
if it has not yet been called.
|
||||
/*! \fn BUnarchiver::~BUnarchiver()
|
||||
\brief Destroys a BUnarchiver object.
|
||||
|
||||
Calls this objects Finish() method, if it has not yet been called.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BUnarchiver::EnsureUnarchived(int32 token)
|
||||
\brief Ensure the object represented by \c token is unarchived and
|
||||
/*! \fn status_t BUnarchiver::EnsureUnarchived(int32 token)
|
||||
\brief Ensure the object represented by \a token is unarchived and
|
||||
instantiated.
|
||||
|
||||
\param token the object \a token
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BUnarchiver::EnsureUnarchived(const char* name,
|
||||
/*! \fn status_t BUnarchiver::EnsureUnarchived(const char* name,
|
||||
int32 index = 0)
|
||||
\brief Ensure the object archived under \c name at \c index is unarchived
|
||||
\brief Ensure the object archived under \a name at \a index is unarchived
|
||||
and instantiated.
|
||||
|
||||
\param name The archive \a name.
|
||||
\param index The archive \a index.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool BUnarchiver::IsInstantiated(int32 token)
|
||||
/*! \fn bool BUnarchiver::IsInstantiated(int32 token)
|
||||
\brief Checks whether the object represented by \c token has been
|
||||
instantiated in this session.
|
||||
|
||||
\param token The object \a token
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
|
||||
\brief Checks whether the object archived under \c name at \c index has been
|
||||
/*! \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
|
||||
\brief Checks whether the object archived under \a name at \a index has been
|
||||
instantiated in this session.
|
||||
|
||||
\param name The archive \a name.
|
||||
\param index The arcive \a token.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
|
||||
/*! \fn template<class T> status_t BUnarchiver::GetObject(int32 token,
|
||||
ownership_policy owning, T*& object)
|
||||
|
||||
\brief Recover an object by token that was archived by a BArchiver object.
|
||||
If the object has not yet been instantiated, and this request is not coming
|
||||
from an AllUnarchived() implementation, the object will be instantiated now.
|
||||
|
||||
If the retrieved object is not of the type \c T, then this method will fail.
|
||||
If the retrieved object is not of the type T, then this method will fail.
|
||||
If this method fails, you will not receive ownership of the object, no
|
||||
matter what you specified in \c owning.
|
||||
|
||||
\tparam T The type of object you wish to find.
|
||||
\tparam T The type of \a object you wish to find.
|
||||
|
||||
\param token The token you got for this object from
|
||||
\param token The \a token you got for this object from
|
||||
BArchiver::GetTokenForArchivable() during archival.
|
||||
\param owning Whether or not you wish to take ownership of the
|
||||
retrieved object.
|
||||
\param object Return parameter for the retrieved object of type \c T.
|
||||
\param object Return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_BAD_TYPE The object retrieved was not of type \c T.
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::GetObject(int32 token,
|
||||
/*! \fn template<class T> status_t BUnarchiver::GetObject(int32 token,
|
||||
T*& object)
|
||||
|
||||
\brief Recover and take ownership of an object represented by \c token.
|
||||
\brief Recover and take ownership of an object represented by \a token.
|
||||
|
||||
Equivalent to calling GetObject(token, BUnarchiver::B_ASSUME_OWNERSHIP,
|
||||
object)
|
||||
Equivalent to calling GetObject(token, \c B_ASSUME_OWNERSHIP, object)
|
||||
|
||||
\tparam T The type of \a object you wish to find.
|
||||
|
||||
\param token The \a token you got for this object from
|
||||
BArchiver::GetTokenForArchivable() during archival.
|
||||
\param object The return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
@@ -137,7 +148,7 @@
|
||||
instantiated, and this request is not coming from an AllUnarchived()
|
||||
implementation, the object will be instantiated now.
|
||||
|
||||
If the retrieved object is not of the type \c T, then this method will fail.
|
||||
If the retrieved object is not of the type T, then this method will fail.
|
||||
If this method fails, you will not receive ownership of the object, no
|
||||
matter what you specified in \c owning.
|
||||
|
||||
@@ -145,61 +156,90 @@
|
||||
|
||||
\param name The name that was passed to BArchiver::AddArchivable() when
|
||||
adding this object.
|
||||
\param index The index of the object you wish to recover (0 based, like
|
||||
BMessage::FindData().
|
||||
\param index The index of the object you wish to recover (\c 0-based,
|
||||
like BMessage::FindData().
|
||||
\param owning Dictates whether or not you wish to take ownership of the
|
||||
retrieved object.
|
||||
\param object Return parameter for the retrieved object of type \c T.
|
||||
\param object Return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_BAD_TYPE The object retrieved was not of type \c T.
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
/*! \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
int32 index, T*& object)
|
||||
|
||||
\brief Recover and take ownership of an object that had previously been
|
||||
archived using the BArchiver::AddArchivable() method.
|
||||
|
||||
\tparam T The type of object you wish to find.
|
||||
|
||||
\param name The name that was passed to BArchiver::AddArchivable() when
|
||||
adding this object.
|
||||
\param index The index of the object you wish to recover (\c 0-based,
|
||||
like #BMessage::FindData().
|
||||
\param object Return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
/*! \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
ownership_policy owning, T*& object)
|
||||
|
||||
\brief Recover an object at index 0 that had previously been archived using
|
||||
the BArchiver::AddArchivable() method.
|
||||
\brief Recover an object at index \c 0 that had previously been
|
||||
archived using the BArchiver::AddArchivable() method.
|
||||
|
||||
Equivalent to calling FindObject(name, 0, owning, object).
|
||||
Equivalent to calling FindObject(name, \c 0, owning, object).
|
||||
|
||||
\tparam T The type of \a object you wish to find.
|
||||
|
||||
\param name The name that was passed to BArchiver::AddArchivable() when
|
||||
adding this object.
|
||||
\param owning Dictates whether or not you wish to take ownership of the
|
||||
retrieved object.
|
||||
\param object Return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
/*! \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
|
||||
T*& object)
|
||||
|
||||
\brief Recover and take ownership of an object at index 0 that had
|
||||
\brief Recover and take ownership of an object at index \c 0 that had
|
||||
previously been archived using the BArchiver::AddArchivable() method.
|
||||
|
||||
Equivalent to calling FindObject(name, 0, BUnarchiver::B_ASSUME_OWNERSHIP,
|
||||
object).
|
||||
Equivalent to calling FindObject(name, \c 0,
|
||||
BUnarchiver::B_ASSUME_OWNERSHIP, object).
|
||||
|
||||
\tparam T The type of \a object you wish to find.
|
||||
|
||||
\param name The name that was passed to BArchiver::AddArchivable() when
|
||||
adding this object.
|
||||
\param object Return parameter for the retrieved \a object of type T.
|
||||
|
||||
\retval B_OK The \a object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The \a object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BUnarchiver::Finish(status_t err = B_OK);
|
||||
/*! \fn status_t BUnarchiver::Finish(status_t err = B_OK);
|
||||
\brief Report any unarchiving errors and possibly complete the archiving
|
||||
session.
|
||||
\return The first error reported in this unarchiving session, or B_OK.
|
||||
|
||||
This method may finish an unarchiving session (triggering the call of all
|
||||
instantiated objects' AllUnarchived() methods) if the following conditions
|
||||
are true:
|
||||
\li No errors have been reported to this or any other BUnarchiver object
|
||||
within this session.
|
||||
\li This is the last remaining BUnarchiver that has not had its Finish()
|
||||
method invoked.
|
||||
|
||||
\li No errors have been reported to this or any other BUnarchiver
|
||||
object within this session.
|
||||
\li This is the last remaining BUnarchiver that has not had its
|
||||
Finish() method invoked.
|
||||
|
||||
If you call this method with an error code not equal to B_OK, then this
|
||||
unarchiving session has failed, instantiated objects will not have their
|
||||
AllUnarchived() methods called, and any subsequent calls to this method
|
||||
@@ -207,22 +247,22 @@
|
||||
Furthermore, any objects that have been instantiated, but have not had
|
||||
their ownership assumed by another object will now be deleted (excluding
|
||||
the root object).
|
||||
|
||||
\return The first error reported in this unarchiving session, or \c B_OK.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn const BMessage* BUnarchiver::ArchiveMessage() const
|
||||
\brief Returns the BMessage* used to construct this BUnarchiver. This is
|
||||
the archive that FindObject() uses.
|
||||
\brief Returns the BMessage* used to construct this BUnarchiver.
|
||||
|
||||
This is the archive that FindObject() uses.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
|
||||
/*! \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
|
||||
|
||||
\brief Checks whether \c archive was managed by a BArchiver object.
|
||||
\retval true if \c archive was managed by a BArchiver object.
|
||||
\retval false otherwise.
|
||||
\brief Checks whether \a archive was managed by a BArchiver object.
|
||||
|
||||
This method can be used to maintain archive backwards-compatibility for a
|
||||
class that has been updated to use the BArchiver class. If there is a
|
||||
@@ -231,7 +271,7 @@
|
||||
object.
|
||||
|
||||
Here is an example of how you might use this method. Note that you
|
||||
must still call BUnarchiver::PrepareArchive(archive), either way.
|
||||
must still call PrepareArchive(archive) either way.
|
||||
|
||||
\code
|
||||
MyArchivableClas::MyArchivableClass(BMessage* archive)
|
||||
@@ -247,14 +287,14 @@ MyArchivableClas::MyArchivableClass(BMessage* archive)
|
||||
}
|
||||
}
|
||||
\endcode
|
||||
|
||||
\retval true if \a archive was managed by a BArchiver object.
|
||||
\retval false otherwise.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn static BMessage* BUnarchiver::PrepareArchive(BMessage*& archive)
|
||||
/*! \fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive)
|
||||
\brief Prepares \c archive for use by a BUnarchiver.
|
||||
\param archive The archive you wish to have prepared.
|
||||
\return The same BMessage as is passed in.
|
||||
|
||||
This method must be called if you plan to use a BUnarchiver on an archive.
|
||||
It must be called once for each class an object inherits from that
|
||||
@@ -272,33 +312,45 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
|
||||
// ...
|
||||
}
|
||||
\endcode
|
||||
|
||||
\param archive The archive you wish to have prepared.
|
||||
|
||||
\return The same #BMessage as is passed in.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
|
||||
\brief Become the owner of \c archivable.
|
||||
/*! \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
|
||||
\brief Become the owner of \a archivable.
|
||||
|
||||
After calling this method, you are responsible for the deletion
|
||||
of \c archivable.
|
||||
After calling this method you are responsible for deleting the
|
||||
\a archivable.
|
||||
|
||||
\param archivable The \a archivable object.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
|
||||
\brief Relinquish ownership of \c archivable. If \c archivable remains
|
||||
/*! \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
|
||||
\brief Relinquish ownership of \a archivable. If \a archivable remains
|
||||
unclaimed at the end of the unarchiving session, it will be deleted
|
||||
(unless it is the root object).
|
||||
|
||||
\param archivable The \a archivable object.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn template<class T> status_t BUnarchiver::InstantiateObject(
|
||||
/*! \fn template<class T> status_t BUnarchiver::InstantiateObject(
|
||||
BMessage* from, T*& object)
|
||||
\brief Attempt to instantiate an object of type \c T from BMessage* \c from.
|
||||
\brief Attempt to instantiate an object of type T from BMessage*
|
||||
\a from.
|
||||
|
||||
If the instantiated object is not of type \c T, then it will be deleted,
|
||||
If the instantiated object is not of type T, then it will be deleted,
|
||||
and this method will return \c B_BAD_TYPE. This method is similar to
|
||||
the instantiate_object() function, but provides error reporting and
|
||||
protection from memory leaks.
|
||||
|
||||
\param from The #BMessage to instantiate from.
|
||||
\param object Return parameter for the retrieved object of type T.
|
||||
|
||||
\retval B_OK The object retrieved was of type T.
|
||||
\retval B_BAD_TYPE The object retrieved was not of type T.
|
||||
*/
|
||||
|
||||
+1151
-770
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user