i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Big docs cleanup.

Browse Source 
* Fixed headers including:
  - All rights reserved not All Rights Reserved.
  - name, [email protected] not name <[email protected]>
  - tabs and spaces
  - Authors: not Documented by:
* Renamed string.dox to String.dox
* Renamed midixxx.dox files to MidiXxx.dox
* Moved images into images subdirectories and updated Doxfile.
* Re-format all files with tabs instead of spaces.
* Fix many spelling mistakes.
* Added all files, classes, structs, and enums to libbe group.
This commit is contained in:
John Scipione
2013-02-07 02:01:19 -05:00
parent 8cf4ba89b6
commit 820dca4df6
109 changed files with 6698 additions and 5170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/Archivable.dox
+24 -15
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -11,18 +11,22 @@
* Thom Holwerda, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
* headers/os/support/Archivable.h rev 37751
* src/kits/support/Archivable.cpp rev 37751
*/
/*! \file Archivable.h
/*!
\file Archivable.h
\ingroup support
\ingroup libbe
\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.
@@ -37,8 +41,8 @@
disk. The objective of this interface, however, is to store objects that
will later be restored as new (but identical) objects. To illustrate this
point, BArchivable objects can be restored automatically to the correct
class, whereas BFlattenables have a data type which you need to map to
classes manually.
class, whereas BFlattenable objects have a data type which you need to map
to classes manually.
Archiving is done with the Archive() method. If your class supports it, the
caller can request it to store into a deep archive, meaning that all child
@@ -65,12 +69,12 @@
/*!
\fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does important behind-the-scenes work in the unarchiving
process.
\brief Constructor. Does important behind-the-scenes work in the
unarchiving process.
If you inherit this interface you should provide at least one constructor
that takes one BMessage argument. In that constructor, you should call your
parent class' archive constructor (even if your parent class is
that takes one BMessage argument. In that constructor, you should call
your parent class' archive constructor (even if your parent class is
BArchivable).
*/
@@ -130,7 +134,7 @@
/*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
\brief Perform some action (Internal method defined for binary
compatibility purposes).
compatibility purposes).
\internal This method is defined for binary compatibility purposes, it is
used to ensure that the correct AllUnarchived() and AllArchived()
@@ -184,13 +188,18 @@
///// Global methods /////
/*!
\addtogroup support_globals
@{
*/
/*! \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.
*/
docs/user/support/Archiver.dox
+11 -3
View File
@@ -1,16 +1,24 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Author:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
* headers/os/support/Archivable.h rev 37751
* src/kits/support/Archivable.cpp rev 37751
*/
/*!
\file Archivable.h
\ingroup support
\ingroup libbe
\brief Contains BArchiver class.
*/
/*!
\class BArchiver
\ingroup support
docs/user/support/Autolock.dox
+76 -69
View File
@@ -1,114 +1,121 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Autolock.h rev 19972
* headers/os/support/Autolock.h rev 19972
*/
/*!
\file Autolock.h
\brief Implements a handy locking utility.
\file Autolock.h
\ingroup support
\ingroup libbe
\brief Implements a handy locking utility.
*/
/*!
\class BAutolock
\ingroup support
\ingroup libbe
\brief Convenient utility to make parts of your code thread-safe easily.
\class BAutolock
\ingroup support
\ingroup libbe
\brief Convenient utility to make parts of your code thread-safe easily.
The autolocker uses a BLooper or a BLocker in order to protect a part
of your code. This class is usually used in combination with a BLocker
that protects a certain part of your code and data that are being
accessed by multiple threads. While BAutolock does not add any features
to locking, it provides a mechanism to easily lock and protect a part of your
code.
The autolocker uses a BLooper or a BLocker in order to protect a part
of your code. This class is usually used in combination with a BLocker
that protects a certain part of your code and data that are being
accessed by multiple threads. While BAutolock does not add any features
to locking, it provides a mechanism to easily lock and protect a part of your
code.
Normally, when you need to protect data, you would have to make sure that
all your locks are paired with unlocks. Below is a simple example, but you
can imagine that there are more complex situations where you might spend a
lot of time debugging a hang because you didn't pair all the Lock()s with an
Unlock(). See the example:
Normally, when you need to protect data, you would have to make sure that
all your locks are paired with unlocks. Below is a simple example, but you
can imagine that there are more complex situations where you might spend a
lot of time debugging a hang because you didn't pair all the Lock()s with an
Unlock(). See the example:
\code
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success)
{
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success)
{
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
}
\endcode
With the BAutolock this example can be rewritten as follows:
With the BAutolock this example can be rewritten as follows:
\code
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
}
\endcode
Since the object is created on stack, it is destroyed as soon as we leave
the function. Because the destruction of the object causes it to unlock
the BLocker or BLooper, you don't have to manually make sure that every
exit from the function is properly unlocked.
Since the object is created on stack, it is destroyed as soon as we leave
the function. Because the destruction of the object causes it to unlock
the BLocker or BLooper, you don't have to manually make sure that every
exit from the function is properly unlocked.
*/
/*!
\fn BAutolock::BAutolock(BLooper *looper)
\brief Create an object and lock the BLooper
\fn BAutolock::BAutolock(BLooper *looper)
\brief Create an object and lock the BLooper
*/
/*!
\fn BAutolock::BAutolock(BLocker *locker)
\brief Create an object and lock the BLocker
\fn BAutolock::BAutolock(BLocker *locker)
\brief Create an object and lock the BLocker
*/
/*!
\fn BAutolock::BAutolock(BLocker &locker)
\brief Create an object and lock the BLocker
\fn BAutolock::BAutolock(BLocker &locker)
\brief Create an object and lock the BLocker
*/
/*!
\fn BAutolock::~BAutolock()
\brief Destroy the object and unlock the associated BLocker or BLooper
\fn BAutolock::~BAutolock()
\brief Destroy the object and unlock the associated BLocker or BLooper
*/
/*!
\fn bool BAutolock::IsLocked(void)
\brief Verify whether the associated BLocker or BLooper are actually locked.
\fn bool BAutolock::IsLocked(void)
\brief Verify whether the associated BLocker or BLooper are actually
locked.
Basically you may assume that when the object is created, you are
almost always sure the actual locking succeeds. It might fail if the
BLocker or BLooper are destroyed though. The semaphore will be
released and the Lock() call will fail.
Basically you may assume that when the object is created, you are
almost always sure the actual locking succeeds. It might fail if the
BLocker or BLooper are destroyed though. The semaphore will be
released and the Lock() call will fail.
If you expect this to happen, you can use this method to help you
protect yourself from any harm.
\retval true The lock was acquired.
\retval false Failed to acquire the lock.
If you expect this to happen, you can use this method to help you
protect yourself from any harm.
\retval true The lock was acquired.
\retval false Failed to acquire the lock.
*/
docs/user/support/Beep.dox
+32 -25
View File
@@ -1,54 +1,61 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Beep.h rev 19972
* /trunk/src/kits/support/Beep.cpp rev 20711
* headers/os/support/Beep.h rev 19972
* src/kits/support/Beep.cpp rev 20711
*/
/////!!!!!! Note that the workings of the beep still aren't completely clear
///// and not completely implemented, so this needs revision if everything
///// is finished.
/*!
\file Beep.h
\brief Functions to generate sounds from the computer.
*/
/////!!!!!! Note that the workings of the beep still aren't completely clear
///// and not completely implemented, so this needs revision if everything
///// is finished.
/*!
\addtogroup support_globals
\file Beep.h
\ingroup support
\ingroup libbe
\brief Functions to generate sounds from the computer.
*/
/*!
\addtogroup support_globals
*/
//! @{
/*! \fn status_t beep()
/*!
\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()
*/
/*! \fn status_t system_beep(const char* eventName)
/*!
\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().
From Beep.h and in libbe.so.
*/
/*! \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
/*!
\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.
From Beep.h and in libbe.so.
\param eventName The name of the event.
\param flags Currently unused. Pass \c 0.
*/
//! @}
docs/user/support/BlockCache.dox
+8 -6
View File
@@ -1,22 +1,24 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Proofreading:
* David Weizades, [email protected]
* David Weizades, [email protected]
* Thom Holwerda, [email protected]
*
*
* Corresponds to:
* /trunk/headers/os/support/BlockCache.h rev 19972
* /trunk/src/kits/support/BlockCache.cpp rev 4568
* headers/os/support/BlockCache.h rev 19972
* src/kits/support/BlockCache.cpp rev 4568
*/
/*!
\file BlockCache.h
\ingroup support
\ingroup libbe
\brief Implements a mechanism to store and retrieve memory blocks.
*/
docs/user/support/BufferIO.dox
+162 -138
View File
@@ -1,184 +1,208 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007,Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Stefano Ceccherini ([email protected])
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/BufferIO.h rev 19972
* /trunk/src/kits/support/BufferIO.cpp rev 20510
* headers/os/support/BufferIO.h rev 19972
* src/kits/support/BufferIO.cpp rev 20510
*/
/*!
\file BufferIO.h
\brief Provides the BBufferIO class.
\file BufferIO.h
\ingroup support
\ingroup libbe
\brief Provides the BBufferIO class.
*/
/*!
\class BBufferIO
\ingroup support
\ingroup libbe
\brief A buffered adapter for BPositionIO objects.
\author Stefano Ceccherini \<[email protected]\>
This class differs from other classes derived from BPositionIO in a sense
that it does not actually provide an actual entity to be read or written
to, but rather acts like a "frontend" to a stream. This class especially
comes in handy when working with files that are constantly written and
rewritten and where you want do this writing buffered so that the hard
disk or the network will not have to be accessed so frequently.
This class works as follows. After constructing a BBufferIO object that
you want to be buffered, you can create this object. The constructor
takes a \a stream parameter that points to the object to be buffered.
You then use this object as a proxy to the resource you want to read
of or write to. As soon as you use ReadAt(), the buffer will be
initialized to the contents of the original stream, and subsequent calls
to the positions within the buffer will not be routed to the original
stream. In the same way WriteAt() will change the data in the buffer,
but not in the actual stream. In order to flush the changes to the
original stream, use the Flush() method. Deleting the object when you are
done with it will also flush the stream and update the original stream.
\note This class is not meant to be used in cases where the
original stream requires to be in a consistent state. Neither should
this class be used as a way to perform 'atomic' writes, because the
object might need to do partial writes if it needs to 'move' the
buffer. This happens for instance if the original stream is bigger
than the buffer.
*/
/*!
\class BBufferIO
\ingroup support
\ingroup libbe
\brief A buffered adapter for BPositionIO objects.
\author Stefano Ceccherini \<[email protected]\>
\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize,
bool ownsStream)
\brief Initialize a BBufferIO object.
This class differs from other classes derived from BPositionIO in a sense that
it does not actually provide an actual entity to be read or written to, but
rather acts like a "frontend" to a stream. This class especially comes in
handy when working with files that are constantly written and rewritten and
where you want do this writing buffered so that the hard disk or the network
will not have to be accessed so frequently.
The constructor will create a buffer of the given size
and associate the object with the given BPositionIO stream.
This class works as follows. After constructing a BBufferIO object that you
want to be buffered, you can create this object. The constructor takes a
\a stream parameter that points to the object to be buffered. You then use
this object as a proxy to the resource you want to read of or write to. As
soon as you use ReadAt(), the buffer will be initialised to the contents
of the original stream,
and subsequent calls to the positions within the buffer will not be
routed to the original stream. In the same way WriteAt() will change
the data in the buffer, but not in the actual stream. In order to flush
the changes to the original stream, use the Flush() method. Deleting
the object when you are done with it will also flush the stream and
update the original stream.
\note This class is not meant to be used in cases where the
original stream requires to be in a consistent state. Neither should this
class be used as a way to perform 'atomic' writes, because the object
might need to do partial writes if it needs to 'move' the buffer. This
happens for instance if the original stream is bigger than the buffer.
\param stream A pointer to a BPositionIO object.
\param bufferSize The size of the buffer that the object will allocate and
use.
\param ownsStream Specifies if the object will delete the stream on
destruction.
*/
/*!
\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, bool ownsStream)
\brief Initialize a BBufferIO object.
The constructor will create a buffer of the given size
and associate the object with the given BPositionIO stream.
\fn BBufferIO::~BBufferIO()
\brief Free the resources allocated by the object
\param stream A pointer to a BPositionIO object.
\param bufferSize The size of the buffer that the object will allocate and
use.
\param ownsStream Specifies if the object will delete the stream on
destruction.
*/
/*!
\fn BBufferIO::~BBufferIO()
\brief Free the resources allocated by the object
Flush pending changes to the stream and free the allocated memory.
If the \c owns_stream property is \c true, the destructor also
deletes the stream associated with the BBufferIO object.
Flush pending changes to the stream and free the allocated memory.
If the \c owns_stream property is \c true, the destructor also
deletes the stream associated with the BBufferIO object.
*/
/*!
\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read the specified amount of bytes at the given position.
\param pos The offset into the stream where to read.
\param buffer A pointer to a buffer where to copy the read data.
\param size The amount of bytes to read.
\return The amount of bytes actually read, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read the specified amount of bytes at the given position.
\param pos The offset into the stream where to read.
\param buffer A pointer to a buffer where to copy the read data.
\param size The amount of bytes to read.
\return The amount of bytes actually read, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
*/
/*!
\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write the specified amount of bytes at the given position.
\param pos The offset into the stream where to write.
\param buffer A pointer to a buffer which contains the data to write.
\param size The amount of bytes to write.
\return The amount of bytes actually written, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write the specified amount of bytes at the given position.
\param pos The offset into the stream where to write.
\param buffer A pointer to a buffer which contains the data to write.
\param size The amount of bytes to write.
\return The amount of bytes actually written, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
*/
/*!
\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
\brief Set the position in the stream.
Set the position in the stream where the Read() and Write() functions
(inherited from BPositionIO) begin reading and writing.
How the position argument is understood depends on the seek_mode flag.
\param position The position where you want to seek.
\param seekMode Can have three values:
- \c SEEK_SET. The position passed is an offset from the beginning of the
stream; in other words, the current position is set to position.
For this mode, position should be a positive value.
- \c SEEK_CUR. The position argument is an offset from the current position;
the value of the argument is added to the current position.
- \c SEEK_END. The position argument is an offset from the end of the
stream. In this mode the position argument should be negative (or zero).
\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
\brief Set the position in the stream.
\return The current position as an offset in bytes from the beginning of
the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
Set the position in the stream where the Read() and Write() functions
(inherited from BPositionIO) begin reading and writing.
How the position argument is understood depends on the seek_mode flag.
/*!
\fn off_t BBufferIO::Position() const
\brief Return the current position in the stream.
\return The current position as an offset in bytes
from the beginning of the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
\param position The position where you want to seek.
\param seekMode Can have three values:
- \c SEEK_SET The position passed is an offset from the beginning of
the stream; in other words, the current position is set to
position. For this mode, position should be a positive value.
- \c SEEK_CUR The position argument is an offset from the current
position; the value of the argument is added to the current
position.
- \c SEEK_END. The position argument is an offset from the end of the
stream. In this mode the position argument should be negative
(or zero).
/*!
\fn status_t BBufferIO::SetSize(off_t size)
\brief Call the SetSize() function of the assigned BPositionIO stream.
\param size The new size of the BPositionIO object.
\retval B_OK The stream is resized.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\return The current position as an offset in bytes from the beginning of
the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::Flush()
\brief Write pending modifications to the stream.
\return The amount of bytes written, or if it failed it will return an error
\fn off_t BBufferIO::Position() const
\brief Return the current position in the stream.
\return The current position as an offset in bytes
from the beginning of the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::SetSize(off_t size)
\brief Call the SetSize() function of the assigned BPositionIO stream.
\param size The new size of the BPositionIO object.
\returns A status code.
\retval B_OK The stream is resized.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::Flush()
\brief Write pending modifications to the stream.
\return The amount of bytes written, or if it failed it will return an error
code.
*/
/*!
\fn BPositionIO *BBufferIO::Stream() const
\brief Return a pointer to the stream specified on construction.
\return A pointer to the BPositionIO stream specified on construction.
\fn BPositionIO *BBufferIO::Stream() const
\brief Return a pointer to the stream specified on construction.
\return A pointer to the BPositionIO stream specified on construction.
*/
/*!
\fn size_t BBufferIO::BufferSize() const
\brief Return the size of the internal buffer.
\return The size of the buffer allocated by the object.
*/
/*!
\fn size_t BBufferIO::BufferSize() const
\brief Return the size of the internal buffer.
/*!
\fn bool BBufferIO::OwnsStream() const
\brief Tell if the BBufferIO object "owns" the specified stream.
\retval true The object "owns" the stream and will destroy it upon
destruction.
\retval false The object does not own the stream.
\see SetOwnsStream()
*/
/*!
\fn void BBufferIO::SetOwnsStream(bool owns_stream)
\brief Set the \c owns_stream property of the object.
\param owns_stream If you pass \c true, the object will delete the stream
upon destruction, if you pass \c false it will not.
\return The size of the buffer allocated by the object.
*/
/*!
\fn void BBufferIO::PrintToStream() const
\brief Print the object to stdout.
/*!
\fn bool BBufferIO::OwnsStream() const
\brief Tell if the BBufferIO object "owns" the specified stream.
\retval true The object "owns" the stream and will destroy it upon
destruction.
\retval false The object does not own the stream.
\see SetOwnsStream()
*/
/*!
\fn void BBufferIO::SetOwnsStream(bool owns_stream)
\brief Set the \c owns_stream property of the object.
\param owns_stream If you pass \c true, the object will delete the stream
upon destruction, if you pass \c false it will not.
*/
/*!
\fn void BBufferIO::PrintToStream() const
\brief Print the object to stdout.
*/
docs/user/support/DataIO.dox
+294 -248
View File
@@ -1,424 +1,470 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Stefano Ceccherini ([email protected])
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/DataIO.h rev 17981
* /trunk/src/kits/support/DataIO.cpp rev 20510
* headers/os/support/DataIO.h rev 17981
* src/kits/support/DataIO.cpp rev 20510
*/
/*!
\file DataIO.h
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
\file DataIO.h
\ingroup support
\ingroup libbe
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
Pure virtual BDataIO and BPositioIO classes provide
the protocol for Read()/Write()/Seek().
Pure virtual BDataIO and BPositioIO classes provide
the protocol for Read()/Write()/Seek().
BMallocIO and BMemoryIO classes implement the protocol,
as does BFile in the Storage Kit.
BMallocIO and BMemoryIO classes implement the protocol,
as does BFile in the Storage Kit.
*/
///// BDataIO /////
/*!
\class BDataIO
\ingroup support
\ingroup libbe
\brief Abstract interface for objects that provide read and write access to
data.
\class BDataIO
\ingroup support
\ingroup libbe
\brief Abstract interface for objects that provide read and write access to
data.
The interface provided by this class applies to objects or data that are
limited to reading and writing data. Classes derived from this class should
reimplement both the Read() and Write() method from this class.
The interface provided by this class applies to objects or data that are
limited to reading and writing data. Classes derived from this class should
re-implement both the Read() and Write() method from this class.
Candidates of types of data or objects that should be derived from this class
are probably broadcasting media streams (which don't support reading at a
certain point in the data) or network streams that output data continously.
Objects and data that support more advanced operations like seeking or
reading at writing at defined positions should derive their classes from
BPositionIO, which inherits this class.
Candidates of types of data or objects that should be derived from this class
are probably broadcasting media streams (which don't support reading at a
certain point in the data) or network streams that output data continuously.
Objects and data that support more advanced operations like seeking or
reading at writing at defined positions should derive their classes from
BPositionIO, which inherits this class.
*/
/*!
\fn BDataIO::BDataIO()
\brief This constructor does nothing.
\fn BDataIO::BDataIO()
\brief This constructor does nothing.
*/
/*!
\fn BDataIO::~BDataIO()
\brief This destructor does nothing.
\fn BDataIO::~BDataIO()
\brief This destructor does nothing.
*/
/*!
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
\brief Pure virtual to read data.
Your implementation should copy data into \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually read, or an error code
/*!
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
\brief Pure virtual to read data.
Your implementation should copy data into \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually read, or an error code
in case of failure.
*/
/*!
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
\brief Pure virtual to write data.
Your implementation should copy data from \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually written, or an error
/*!
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
\brief Pure virtual to write data.
Your implementation should copy data from \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually written, or an error
code in case of failure.
*/
//////////// BPositionIO
/*!
\class BPositionIO
\ingroup support
\ingroup libbe
\brief Abstract interface that provides advanced read, write and seek access
to data.
\class BPositionIO
\ingroup support
\ingroup libbe
\brief Abstract interface that provides advanced read, write and seek access
to data.
The interface of this object applies to objects or data that allows
position-aware reading and writing of data. Classes that derive from this
class should at least reimplement ReadAt(), WriteAt(), Seek(), Position(),
SetSize() and GetSize() methods.
The interface of this object applies to objects or data that allows
position-aware reading and writing of data. Classes that derive from this
class should at least re-implement ReadAt(), WriteAt(), Seek(), Position(),
SetSize() and GetSize() methods.
A good example of a form of data that can derive from this object, are files.
The BFile class derives from BPositionIO and provides this interface to
files. If your object or data only supports linear reading and writing,
consider deriving from the baseclass BDataIO.
A good example of a form of data that can derive from this object, are files.
The BFile class derives from BPositionIO and provides this interface to
files. If your object or data only supports linear reading and writing,
consider deriving from the base-class BDataIO.
A final note, from BDataIO this class inherits Read() and Write(). The
default implementation is to read or write the data at the current position
indicated by Position(). Reimplement the methods if you require a different
behaviour.
A final note, from BDataIO this class inherits Read() and Write(). The
default implementation is to read or write the data at the current position
indicated by Position(). Re-implement the methods if you require a different
behavior.
*/
/*!
\fn BPositionIO::BPositionIO()
\brief This constructor does nothing.
\fn BPositionIO::BPositionIO()
\brief This constructor does nothing.
*/
/*!
\fn virtual BPositionIO::~BPositionIO()
\brief This destructor does nothing.
\fn virtual BPositionIO::~BPositionIO()
\brief This destructor does nothing.
*/
/*!
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
\brief Read data from current position.
This method is derived from BDataIO. The default implementation reads data
from the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Read() for what is
expected of this method.
/*!
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
\brief Read data from current position.
This method is derived from BDataIO. The default implementation reads data
from the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Read() for what is
expected of this method.
*/
/*!
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
\brief Write data to the current position.
This method is derived from BDataIO. The default implementation writes data
to the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Write() for what is
expected of this method.
/*!
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
\brief Write data to the current position.
This method is derived from BDataIO. The default implementation writes data
to the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Write() for what is
expected of this method.
*/
/*!
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
\brief Pure virtual to read data from a certain position.
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
\brief Pure virtual to read data from a certain position.
Your implementation should copy data from the position indicated by
\a position into the \a buffer with the maximum size of \a size.
Your implementation should copy data from the position indicated by
\a position into the \a buffer with the maximum size of \a size.
\return The amount of bytes actually read, or an error code.
\return The amount of bytes actually read, or an error code.
*/
/*!
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
\brief Pure virtual to write data to a certain position.
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
\brief Pure virtual to write data to a certain position.
Your implementation should copy data from \a buffer to the position indicated
by \a buffer with the maximum size of \a size.
Your implementation should copy data from \a buffer to the position indicated
by \a buffer with the maximum size of \a size.
\return The amount of bytes actually written, or an error code.
\return The amount of bytes actually written, or an error code.
*/
/*!
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
\brief Pure virtual to move the cursor to a certain position.
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
\brief Pure virtual to move the cursor to a certain position.
Your implementation should move the position of the cursor to the provided
point. What this actually means, depends on your object or data.
Your implementation should move the position of the cursor to the provided
point. What this actually means, depends on your object or data.
\param position An integer that defines a position.
\param seekMode You will get one of the following values:
\param position An integer that defines a position.
\param seekMode You will get one of the following values:
- \c SEEK_SET Set the cursor to the position indicated by \c position.
- \c SEEK_END Set the cursor to the end of the buffer, and go
\c position beyond that.
- \c SEEK_CUR Set the cursor the the current position plus \c position.
\return The new position.
\return The new position.
*/
/*!
\fn virtual off_t BPositionIO::Position() const = 0
\brief Pure virtual to return the current position of the cursor.
\return Your implementation should return the current position of the cursor.
/*!
\fn virtual off_t BPositionIO::Position() const = 0
\brief Pure virtual to return the current position of the cursor.
\return Your implementation should return the current position of the cursor.
*/
/*!
\fn virtual status_t BPositionIO::SetSize(off_t size)
\brief Set the size of the object or data.
\fn virtual status_t BPositionIO::SetSize(off_t size)
\brief Set the size of the object or data.
The default implementation returns \c B_ERROR. If your object or data allows
the size to be changed, reimplement this method.
The default implementation returns \c B_ERROR. If your object or data allows
the size to be changed, reimplement this method.
\return Return \c B_OK if everything succeeded, else return the appropriate
\return Return \c B_OK if everything succeeded, else return the appropriate
error code.
*/
/*!
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
\brief Get the size of the object or data.
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
\brief Get the size of the object or data.
The default implementation uses Seek() with the \c SEEK_END flag to
determine the size of the buffer. If your data or object has a different way
of determining size, reimplement this method.
The default implementation uses Seek() with the \c SEEK_END flag to
determine the size of the buffer. If your data or object has a different way
of determining size, reimplement this method.
Please check that NULL is not passed into \c size if you reimplement it in
your class.
Please check that NULL is not passed into \c size if you reimplement it in
your class.
\param[out] size The size of the object is put into this parameter.
\return This method returns \c B_OK on success or an error code on error.
\see Seek()
\param[out] size The size of the object is put into this parameter.
\return This method returns \c B_OK on success or an error code on error.
\see Seek()
*/
//////////// BMemoryIO
/*!
\class BMemoryIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that works on memory buffers.
\class BMemoryIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that works on memory buffers.
This class is used if you require access that confirms to the BPositionIO
interface on memory buffers that you created. If you would like to use that
interface on new buffers, have a look at BMallocIO.
This class is used if you require access that confirms to the BPositionIO
interface on memory buffers that you created. If you would like to use that
interface on new buffers, have a look at BMallocIO.
This class is particularly useful if you would like to use a class or method
that are written to make use of the BPositionIO interface. It might also
be used for 'secure' reading and writing from buffers, since this class
automatically checks the bounds of anything you might want to do.
This class is particularly useful if you would like to use a class or method
that are written to make use of the BPositionIO interface. It might also
be used for 'secure' reading and writing from buffers, since this class
automatically checks the bounds of anything you might want to do.
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
Position() interface from BPositionIO.
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
Position() interface from BPositionIO.
*/
/*!
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
\brief Create a read/write object.
\param data A pointer to the buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(const void *buffer, size_t length) for a read-only
/*!
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
\brief Create a read/write object.
\param data A pointer to the buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(const void *buffer, size_t length) for a read-only
implementation.
*/
/*!
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
\brief Create a read-only object.
\param buffer A pointer to the \c const (read-only) buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
/*!
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
\brief Create a read-only object.
\param buffer A pointer to the \c const (read-only) buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
*/
/*!
\fn BMemoryIO::~BMemoryIO()
\brief The destructor does nothing.
\fn BMemoryIO::~BMemoryIO()
\brief The destructor does nothing.
*/
/*!
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read from a given position.
\param[in] pos The offset where to start reading data.
\param[out] buffer The buffer to copy the read bytes into.
\param[in] size The size of the \a buffer.
\return The amount of read bytes or an error code.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
/*!
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read from a given position.
\param[in] pos The offset where to start reading data.
\param[out] buffer The buffer to copy the read bytes into.
\param[in] size The size of the \a buffer.
\return The amount of read bytes or an error code.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
*/
/*!
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write at a given position.
\param pos The offset to write to.
\param buffer The buffer to copy the bytes from.
\param size The number of bytes to write.
\return The amount of bytes written or an error code.
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
/*!
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write at a given position.
\param pos The offset to write to.
\param buffer The buffer to copy the bytes from.
\param size The number of bytes to write.
\return The amount of bytes written or an error code.
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
*/
/*!
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seek_mode The mode determines where the cursor is placed.
/*!
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seek_mode The mode determines where the cursor is placed.
Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \a position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
\return The new position.
*/
/*!
\fn off_t BMemoryIO::Position() const
\brief Return the current position.
\fn off_t BMemoryIO::Position() const
\brief Return the current position.
*/
/*!
\fn status_t BMemoryIO::SetSize(off_t size)
\brief Resize the buffer.
\fn status_t BMemoryIO::SetSize(off_t size)
\brief Resize the buffer.
This method does not actually resize the buffer. If the new size is greater
than the size of the buffer, resizing will fail. It will only succeed if the
new size is less than the size of the buffer. The buffer itself will not be
resized though.
This method does not actually resize the buffer. If the new size is greater
than the size of the buffer, resizing will fail. It will only succeed if the
new size is less than the size of the buffer. The buffer itself will not be
resized though.
This method might be useful in some cases. If the buffer is larger than the
data it holds, changing the size will enable you to use the Seek() method
with the flag \c SEEK_END and not get an error if you read or write from
that position, since you actually have a buffer at the end.
This method might be useful in some cases. If the buffer is larger than the
data it holds, changing the size will enable you to use the Seek() method
with the flag \c SEEK_END and not get an error if you read or write from
that position, since you actually have a buffer at the end.
\retval B_OK The buffer is resized.
\retval B_NOT_ALLOWED The buffer is read-only.
\retval B_ERROR The \c size is larger than the size of the buffer.
\retval B_OK The buffer is resized.
\retval B_NOT_ALLOWED The buffer is read-only.
\retval B_ERROR The \c size is larger than the size of the buffer.
*/
//////////// BMallocIO
/*!
\class BMallocIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that creates a memory buffer.
\class BMallocIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that creates a memory buffer.
This class creates a memory buffer and provides a BPositionIO interface to
work on it. The memory buffer grows and shrinks automatically.
This is especially useful if you want to use a method or function that
works on an object derived from BPositionIO and you want to do something with
the resulting data, or it could be useful if you want to read and write to
memory in a safe way, since this class has boundary checking.
This class creates a memory buffer and provides a BPositionIO interface to
work on it. The memory buffer grows and shrinks automatically.
This is especially useful if you want to use a method or function that
works on an object derived from BPositionIO and you want to do something with
the resulting data, or it could be useful if you want to read and write to
memory in a safe way, since this class has boundary checking.
BMallocIO allocates a buffer based on a certain blocksize. This provides a
mechanism that will prevent it from needing to allocate new memory too often.
The default blocksize is 256 bytes, you can change it with SetBlockSize(). If
you are sure you are going to use a bigger buffer, change the blocksize so
that you won't have to allocate more memory too often, especially if you use
this class in performance-critical code.
BMallocIO allocates a buffer based on a certain block size. This provides a
mechanism that will prevent it from needing to allocate new memory too often.
The default block size is 256 bytes, you can change it with SetBlockSize(). If
you are sure you are going to use a bigger buffer, change the block size so
that you won't have to allocate more memory too often, especially if you use
this class in performance-critical code.
If you require a BPositionIO derived object that works on buffers you
provide, have a look at BMemoryIO.
If you require a BPositionIO derived object that works on buffers you
provide, have a look at BMemoryIO.
*/
/*!
\fn BMallocIO::BMallocIO()
\brief Create a new memory buffer with block size 256.
\see SetBlockSize()
\fn BMallocIO::BMallocIO()
\brief Create a new memory buffer with block size 256.
\see SetBlockSize()
*/
/*!
\fn BMallocIO::~BMallocIO()
\brief Destroy the object and free the internal buffer.
\fn BMallocIO::~BMallocIO()
\brief Destroy the object and free the internal buffer.
*/
/*!
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read data at a certain position.
\param[in] pos Offset into the data where to read from.
\param[out] buffer The buffer to copy the read bytes in.
\param [in] size Size of the buffer.
\return The number of read bytes, or \c B_BAD_VALUE if
/*!
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read data at a certain position.
\param[in] pos Offset into the data where to read from.
\param[out] buffer The buffer to copy the read bytes in.
\param [in] size Size of the buffer.
\return The number of read bytes, or \c B_BAD_VALUE if
the provided \a buffer is invalid.
*/
/*!
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write data to a certain position.
\param pos Offset into the data where to write to.
\param buffer The buffer to copy from.
\param size The size of the buffer.
\return The number of bytes written or \c B_BAD_VALUE if the provided.
\a buffer is invalid.
/*!
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write data to a certain position.
\param pos Offset into the data where to write to.
\param buffer The buffer to copy from.
\param size The size of the buffer.
\return The number of bytes written or \c B_BAD_VALUE if the provided.
\a buffer is invalid.
*/
/*!
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seekMode The mode determines where the cursor is placed. Possibilities:
/*!
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seekMode The mode determines where the cursor is placed. Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \c position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
\return The new position.
*/
/*!
\fn off_t BMallocIO::Position() const
\brief Return the position of the cursor.
\fn off_t BMallocIO::Position() const
\brief Return the position of the cursor.
*/
/*!
\fn status_t BMallocIO::SetSize(off_t size)
\brief Change the size of the buffer.
\fn status_t BMallocIO::SetSize(off_t size)
\brief Change the size of the buffer.
This method changes the size of the current buffer. If \a size is smaller
than the current size, the data will be cleared.
This method changes the size of the current buffer. If \a size is smaller
than the current size, the data will be cleared.
\param size The new size of the buffer.
\retval B_OK Resizing the data succeeded.
\retval B_NO_MEMORY Failed to allocate the necessary memory.
\param size The new size of the buffer.
\retval B_OK Resizing the data succeeded.
\retval B_NO_MEMORY Failed to allocate the necessary memory.
*/
/*!
\fn void BMallocIO::SetBlockSize(size_t blockSize)
\brief Change the block size to a certain value.
\fn void BMallocIO::SetBlockSize(size_t blockSize)
\brief Change the block size to a certain value.
This class allocates memory in blocks. If you are in performance-critical
code you might want to tweak this setting to create a better performance in
case you know you are going to allocate more than the default blocksize of
256.
This class allocates memory in blocks. If you are in performance-critical
code you might want to tweak this setting to create a better performance in
case you know you are going to allocate more than the default blocksize of
256.
\param blockSize The new block size.
\param blockSize The new block size.
*/
/*!
\fn const void *BMallocIO::Buffer() const
\brief Return a pointer to the internal buffer.
\fn const void *BMallocIO::Buffer() const
\brief Return a pointer to the internal buffer.
As with any pointer to internal buffers the Haiku API exposes,
make sure you don't change anything since it doesn't belong to you.
As with any pointer to internal buffers the Haiku API exposes,
make sure you don't change anything since it doesn't belong to you.
*/
/*!
\fn size_t BMallocIO::BufferLength() const
\brief Return the number of bytes in the buffer.
\fn size_t BMallocIO::BufferLength() const
\brief Return the number of bytes in the buffer.
This number doesn't have to be the same size as the buffer is. Because memory
is allocated in blocks the actual size of the buffer may be greater, but this
method only returns the number of bytes that are actually used.
This number doesn't have to be the same size as the buffer is. Because memory
is allocated in blocks the actual size of the buffer may be greater, but this
method only returns the number of bytes that are actually used.
*/
docs/user/support/Flattenable.dox
+157 -140
View File
@@ -1,171 +1,188 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation written by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk <[email protected]>
*
* Corresponds to:
* /trunk/headers/os/support/Flattenable.h rev 19972
* /trunk/src/kits/support/Flattenable.cpp rev 12963
* headers/os/support/Flattenable.h rev 19972
* src/kits/support/Flattenable.cpp rev 12963
*/
/*!
\file Flattenable.h
\brief Provides the BFlattenable interface
*/
/*!
\class BFlattenable
\ingroup support
\ingroup libbe
\brief Interface for classes that can flatten and unflatten themselves to
a stream of bytes.
It is convenient that objects can be stored as a flat stream of bytes. In
this way, they can be written to disk, exchanged between applications or send
over networks. This ability, which is known in many other programming
languages as marshalling, is not native in C++. The Haiku API has created a
universal interface that classes have if they are able to be flattened. This
class defines the interface. This class does nothing on its own, and
therefore contains pure virtuals. By inheriting this class and inmplementing
the methods in your own class, you will be able to use your objects as
flattenable objects throughout the Haiku API.
Flattened objects can be used for example when sending messages within an
application or between applications. The BMessage class uses the interface
to store and transmit custom classes.
If you want to be able to flatten your objects, you will need to implement
various methods. Flatten() and Unflatten() are where the magic happen. These
methods handle the actual flattening and unflattening. To identify flattened
data in for example BMessage, the object has a type_code. Type codes are
four byte long integers. You can choose to flatten to one of the existing
types, if you are certain that you are compatible to those, but you'll
usually define your own type. Your best option is by using a multicharacter
constant, such as 'STRI'. Implement TypeCode() to return the type you
support. Implement FlattenedSize() to make sure that other objects can
provide the right buffers. Implement IsFixedSize() to return whether your
objects always store to a fixed size.
See the following example:
\code
\file Flattenable.h
\ingroup support
\ingroup libbe
\brief Provides the BFlattenable interface
*/
/*!
\class BFlattenable
\ingroup support
\ingroup libbe
\brief Interface for classes that can flatten and unflatten themselves to
a stream of bytes.
It is convenient that objects can be stored as a flat stream of bytes. In
this way, they can be written to disk, exchanged between applications or send
over networks. This ability, which is known in many other programming
languages as marshalling, is not native in C++. The Haiku API has created a
universal interface that classes have if they are able to be flattened. This
class defines the interface. This class does nothing on its own, and
therefore contains pure virtuals. By inheriting this class and inmplementing
the methods in your own class, you will be able to use your objects as
flattenable objects throughout the Haiku API.
Flattened objects can be used for example when sending messages within an
application or between applications. The BMessage class uses the interface
to store and transmit custom classes.
If you want to be able to flatten your objects, you will need to implement
various methods. Flatten() and Unflatten() are where the magic happen. These
methods handle the actual flattening and unflattening. To identify flattened
data in for example BMessage, the object has a type_code. Type codes are
four byte long integers. You can choose to flatten to one of the existing
types, if you are certain that you are compatible to those, but you'll
usually define your own type. Your best option is by using a multicharacter
constant, such as 'STRI'. Implement TypeCode() to return the type you
support. Implement FlattenedSize() to make sure that other objects can
provide the right buffers. Implement IsFixedSize() to return whether your
objects always store to a fixed size.
See the following example:
\code
type_code CUSTOM_STRING_TYPE = 'CUST';
class CustomString : public BFlattenable
{
public:
char data[100];
char data[100];
// From BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
memcpy(buffer, data, size);
return B_OK;
};
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
// From BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
memcpy(buffer, data, size);
return B_OK;
};
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
};
\endcode
Have a look at TypeConstants.h for a list of all the types that the Haiku
API defines.
The Haiku API has a second interface for storing objects, which is with
BArchivable. BArchivable is for more complex cases. Instead of one flat
datastream, it stores an object in a BMessage. In that way you can reflect
internals of a class better. It also provides an interface for instantiating
objects, that is, for objects to restore themselves from a BMessage. In
essence, BArchivable is more suitable for objects that are alive. In short
BFlattenable is for data objects, BArchivable is for 'live' objects.
Other classes in the API that support flattening and unflattening are for
example BMessage, which enables you to conveniently write flattened data
to disk. Another example is BPath. Because of that you can store paths and
send them over via messages. Throughout the Haiku API you will find classes
that provide the flattening interface.
\endcode
Have a look at TypeConstants.h for a list of all the types that the Haiku
API defines.
The Haiku API has a second interface for storing objects, which is with
BArchivable. BArchivable is for more complex cases. Instead of one flat
datastream, it stores an object in a BMessage. In that way you can reflect
internals of a class better. It also provides an interface for instantiating
objects, that is, for objects to restore themselves from a BMessage. In
essence, BArchivable is more suitable for objects that are alive. In short
BFlattenable is for data objects, BArchivable is for 'live' objects.
Other classes in the API that support flattening and unflattening are for
example BMessage, which enables you to conveniently write flattened data
to disk. Another example is BPath. Because of that you can store paths and
send them over via messages. Throughout the Haiku API you will find classes
that provide the flattening interface.
*/
/*!
\fn virtual bool BFlattenable::IsFixedSize() const = 0
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
*/
/*!
\fn virtual type_code BFlattenable::TypeCode() const = 0
\brief Pure virtual that should return which type_code this class flattens
to.
\return Either one of the existing typecodes, found in TypeConstants.h,
<em>if your class actually is compatible to those formats</em>, or a custom
four byte integer constant.
\fn virtual bool BFlattenable::IsFixedSize() const
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
*/
/*!
\fn virtual ssize_t BFlattenable::FlattenedSize() const = 0
\brief Pure virtual that should return the size of the flattened object in
bytes.
*/
/*!
\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const = 0
\brief Pure virtual that should flatten the object into the supplied
\a buffer.
Please make sure that you check that the supplied buffer is not a \c NULL
pointer. Also make sure that the size of the flattened object does isn't
larger than the size of the buffer.
\param buffer The buffer to flatten in.
\param size The size of the buffer.
\retval B_OK The object was flattened.
\retval B_NO_MEMORY The buffer was smaller than required.
\retval B_BAD_VALUE The buffer was a \c NULL pointer.
\fn virtual type_code BFlattenable::TypeCode() const
\brief Pure virtual that returns the type_code this class flattens to.
\return Either one of the existing typecodes found in TypeConstants.h
if your class actually is compatible to those formats, or a
custom four-byte integer constant if not.
*/
/*!
\fn bool BFlattenable::AllowsTypeCode(type_code code) const
\brief Return whether or not the supplied type_code is supported.
This default implementation checks the \a code argument against the type_code
returned by TypeCode().
\param code The type_code constant you want to check for.
\retval true The type_code is supported.
\retval false The type_code is not supported.
*/
/*!
\fn virtual status_t BFlattenable::Unflatten(type_code code, const void* buffer, ssize_t size) = 0
\brief Pure virtual that should unflatten the buffer and put the contents
into the current object.
Make sure that the supplied buffer is not \c NULL and that you actually
support the typecode.
\param code The type_code this data is.
\param buffer The buffer to unflatten the data from.
\param size The size of the data.
\retval B_OK The object is unflattened.
\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
\retval B_BAD_TYPE You don't support data with this \a code.
\fn virtual ssize_t BFlattenable::FlattenedSize() const
\brief Pure virtual that should return the size of the flattened object in
bytes.
*/
/*!
\fn virtual BFlattenable::~BFlattenable()
\brief Destructor. Does nothing.
\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const
\brief Pure virtual that should flatten the object into the supplied
\a buffer.
Please make sure that you check that the supplied buffer is not a \c NULL
pointer. Also make sure that the size of the flattened object does isn't
larger than the size of the buffer.
\param buffer The buffer to flatten in.
\param size The size of the buffer.
\retval B_OK The object was flattened.
\retval B_NO_MEMORY The buffer was smaller than required.
\retval B_BAD_VALUE The buffer was a \c NULL pointer.
*/
/*!
\fn bool BFlattenable::AllowsTypeCode(type_code code) const
\brief Get whether or not the supplied type_code is supported.
This default implementation checks the \a code argument against the type_code
returned by TypeCode().
\param code The type_code constant you want to check for.
\returns Whether or not the supplied type_code is supported.
\retval true The type_code is supported.
\retval false The type_code is not supported.
*/
/*!
\fn virtual status_t BFlattenable::Unflatten(type_code code,
const void* buffer, ssize_t size)
\brief Pure virtual that should unflatten the buffer and put the contents
into the current object.
Make sure that the supplied buffer is not \c NULL and that you actually
support the typecode.
\param code The type_code this data is.
\param buffer The buffer to unflatten the data from.
\param size The size of the data.
\returns A status code.
\retval B_OK The object is unflattened.
\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
\retval B_BAD_TYPE You don't support data with this \a code.
*/
/*!
\fn virtual BFlattenable::~BFlattenable()
\brief Destructor. Does nothing.
*/
docs/user/support/List.dox
+44 -84
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -11,13 +11,15 @@
* John Drinkwater, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/List.h rev 19972
* /trunk/src/kits/support/List.cpp rev 18649
* headers/os/support/List.h rev 19972
* src/kits/support/List.cpp rev 18649
*/
/*!
\file List.h
\ingroup support
\ingroup libbe
\brief Defines the BList class.
*/
@@ -28,37 +30,36 @@
\ingroup libbe
\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
implementations in other libraries, this class is not based on templates
and as such is inherently not typed. So it will be the job of the programmer
to make sure proper data is entered since the compiler cannot check this by
itself.
BList contains a list of items that will grow and shrink depending on how
many items are in it. So you will not have to do any of the memory
management nor any ordering. These properties makes it useful in a whole
range of situations such as the interface kit within the BListView class.
A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects. As such, removing items from the list will
only remove the entries from the list; it will not delete the items
themselves. Similarly, you should also make sure that before you might
delete an object that is in a list, you will have to remove it from the list
first.
\warning This class is not thread-safe.
The class implements methods to add, remove, reorder, retrieve, and query
items as well as some advanced methods which let you perform a task on all
the items in the list.
*/
/*!
\fn BList::BList(int32 count = 20)
\brief Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The
\c count parameter can be tweaked to determine the size of these blocks.
In general, if you know your list is only going to contain a certain number
@@ -68,49 +69,43 @@
large number of items, choose a higher value. Every time the memory is full,
all the items have to be copied into a new piece of allocated memory, which
is an expensive operation.
If you are unsure, you do not have to worry too much. Just make sure you do
not use a lot of lists, and as long as the list is not used in one of the
performance critical parts of the code, you are safe to go with the default
values.
\param count The size of the blocks allocated in memory.
*/
/*!
\fn BList::BList(const BList& anotherList)
\brief Copy constructor. Copy a complete list into this one.
*/
/*!
\fn BList::~BList()
\brief Destroy the list.
Please note that as BList does not assume ownership of the objects,
only the list will be freed, not the objects that are held in it.
*/
/*!
\fn BList& BList::operator=(const BList &list)
\brief Copy another list into this object.
*/
/*!
\name Adding and Removing Items
*/
//! @{
/*!
\fn bool BList::AddItem(void *item, int32 index)
\brief Add an item at a certain position.
\param item The item to add.
\param index The place in the list.
\retval true The item was added.
@@ -119,25 +114,23 @@
\see AddItem(void *item)
*/
/*!
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
\param item The item to add.
\retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\see AddItem(void *item, int32 index)
*/
/*!
\fn bool BList::AddList(const BList *list, int32 index)
\brief Add items from another list to this list at a certain position.
Note that the \a list parameter is \c const, so the original list will not
be altered.
\param list The list to be added.
\param index The position in the current list where the new item(s) should
be put.
@@ -147,14 +140,13 @@
\see AddList(const BList *list)
*/
/*!
\fn bool BList::AddList(const BList *list)
\brief Append a list to this list.
Note that the \a list parameter is a \c const, so the original list will not
be altered.
\param list The list to be appended.
\retval true The list was appended.
\retval false Failed to append the list, due to the fact that resizing of
@@ -162,160 +154,142 @@
\see AddList(const BList *list, int32 index)
*/
/*!
\fn bool BList::RemoveItem(void *item)
\brief Remove an item from the list.
\param item The item that should be removed.
\retval true The item was found and removed.
\retval false The item was not in this list and thus not removed.
\see RemoveItem(int32 index)
*/
/*!
\fn void * BList::RemoveItem(int32 index)
\brief Remove the item at \a index from the list.
\param index The item that should be removed.
\return The pointer to the item that was removed, or \c NULL in case the
index was invalid.
\see RemoveItem(void *item)
*/
/*!
\fn bool BList::RemoveItems(int32 index, int32 count)
\brief Remove a number of items starting at a certain position.
If the count parameter is larger than the number of items in the list,
all the items from the offset to the end will be removed.
\param index The offset in the list where removal should start.
\param count The number of items to remove.
\retval true Removal succeeded.
\retval false Failed to remove the items because the index was invalid.
*/
/*!
\fn bool BList::ReplaceItem(int32 index, void *newItem)
\brief Replace an item with another one.
\param index The offset in the list where to put the item.
\param newItem The new item to put in the list.
\retval true Item replaced.
\retval false The index was invalid.
*/
/*!
\fn void BList::MakeEmpty()
\brief Clear all the items from the list.
Please note that this does not free the items.
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\brief Sort the items with the use of a supplied comparison function.
The function should take two \c const pointers as arguments and should
return an integer.
For an example, see the Compare(const BString *, const BString *) function.
*/
/*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
\brief Swap two items.
\param indexA The first item.
\param indexB The second item.
\retval true Swap succeeded.
\retval false Swap failed because one of the indexes was invalid.
*/
/*!
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place
This moves a list item from position A to position B, moving the appropriate
block of list elements to make up for the move. For example, in the array:
\verbatim
A B C D E F G H I J
\endverbatim
Moving 1(B)->6(G) would result in this:
\verbatim
A C D E F G B H I J
\endverbatim
\param fromIndex The original location.
\param toIndex The new location.
\retval true Move succeeded.
\retval false Move failed due to the indexes being invalid.
*/
//! @}
/*!
\name Retrieving Items
*/
//! @{
/*!
\fn void *BList::ItemAt(int32 index) const
\brief Get an item.
\param index The item to retrieve.
\return A pointer to the item in that position, or \c NULL if the index is
out of bounds.
\see ItemAtFast(int32 index) const
*/
/*!
\fn void *BList::FirstItem() const
\brief Get the first item.
\return A pointer to the first item or \c NULL if the list is empty.
\see LastItem() const
*/
/*!
\fn void *BList::ItemAtFast(int32 index) const
\brief Get an item.
This method does not perform any boundary checks when it retrieves an item.
Use this method in a performance critical area of your program where you are
sure you will not get an invalid item.
\return A pointer to the item.
*/
/*!
\fn void *BList::LastItem() const
\brief Get the last item.
@@ -323,18 +297,17 @@ A C D E F G B H I J
\see FirstItem() const
*/
/*!
\fn void *BList::Items() const
\brief Return the internal list of objects.
This method will return a pointer to the internal pointer list. This means
that you should be careful what you are doing, since you are working with
the internals of the class directly.
It is not a good idea to make any changes to the list, since that will mess
up the internal consistency.
\warning If there is anything you want, for which you need the list of
objects, please realize that that probably means that what you want to
do is a bad idea to begin with and that you should avoid this method.
@@ -343,75 +316,63 @@ A C D E F G B H I J
\return The internal list of pointers.
*/
//! @}
/*!
\name Querying for Items
*/
//! @{
/*!
\fn bool BList::HasItem(void *item) const
\brief Check if an item is in the list.
*/
/*!
\fn int32 BList::IndexOf(void *item) const
\brief Get the index of an item.
\return The index of the item, or -1 when the item is not in the list.
*/
/*!
\fn int32 BList::CountItems() const
\brief Get the number of items in the list.
*/
/*!
\fn bool BList::IsEmpty() const
\brief Check if there are items in the list.
*/
//! @}
/*!
\name Iterating over the List
*/
//! @{
/*!
\fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list.
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
boolean.
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
*/
/*!
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\brief Perform an action on every item in the list with an argument.
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
return a boolean value on whether it succeeded or not.
@@ -419,5 +380,4 @@ A C D E F G B H I J
\see DoForEach(bool (*func)(void* item))
*/
//! @}
docs/user/support/Locker.dox
+139 -134
View File
@@ -1,203 +1,208 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Locker.h rev 19972
* /trunk/src/kits/support/Locker.cpp rev 13826
* headers/os/support/Locker.h rev 19972
* src/kits/support/Locker.cpp rev 13826
*/
/*!
\file Locker.h
\brief Provides locking class BLocker.
\file Locker.h
\ingroup support
\ingroup libbe
\brief Provides locking class BLocker.
*/
/*!
\class BLocker
\ingroup support
\ingroup libbe
\brief Semaphore-type class for thread safety.
\class BLocker
\ingroup support
\ingroup libbe
\brief Semaphore-type class for thread safety.
The BLocker interface is not merely a wrapper around a semaphore, but it
also has two advantages. First of all, it implements a benaphore.
A benaphore is in some ways more speed efficient,
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a variable
is a lot more efficient than acquiring a semaphore, thus this type of locking
is much prefered.
The BLocker interface is not merely a wrapper around a semaphore, but it
also has two advantages. First of all, it implements a benaphore.
A benaphore is in some ways more speed efficient,
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a variable
is a lot more efficient than acquiring a semaphore, thus this type of locking
is much prefered.
It basically works as follows. Whenever you newly created BLocker object
recieves a locking request, it atomically sets the benaphore variable to
\c 1. Then only additional calls from different threads will utilize the
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads, but
the chances of it happening being very small, the benaphore benefits the
most from it's speed.
It basically works as follows. Whenever you newly created BLocker object
recieves a locking request, it atomically sets the benaphore variable to
\c 1. Then only additional calls from different threads will utilize the
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads, but
the chances of it happening being very small, the benaphore benefits the
most from it's speed.
The other feature of BLocker that improves basic semaphore handling is that
it allows for recursive locks. The following piece of code works with a
BLocker, but block inevitably with a semaphore. Let's pretend I call
The other feature of BLocker that improves basic semaphore handling is that
it allows for recursive locks. The following piece of code works with a
BLocker, but block inevitably with a semaphore. Let's pretend I call
\c Water():
\code
status_t
Flower::Grow(int length)
{
\code
status_t
Flower::Grow(int length)
{
if (fLock->Lock()) {
fLength += length;
fLock->Unlock();
return B_OK;
fLength += length;
fLock->Unlock();
return B_OK;
} else {
return B_ERROR;
return B_ERROR;
}
}
}
status_t
Flower::Water(int amount)
{
status_t
Flower::Water(int amount)
{
if (fLock->Lock()) {
status_t status = Grow(amount * 2);
fLock->Unlock();
return status;
status_t status = Grow(amount * 2);
fLock->Unlock();
return status;
} else {
return B_ERROR;
return B_ERROR;
}
}
\endcode
}
\endcode
This code would work because BLocker keeps track of the amount of lock
requests from the same thread. A normal semaphore would block in \c Grow()
because the semaphore would be acquired already. Please do make sure you
pair every Lock() with an Unlock() though, or you'll create a deadlock.
This code would work because BLocker keeps track of the amount of lock
requests from the same thread. A normal semaphore would block in \c Grow()
because the semaphore would be acquired already. Please do make sure you
pair every Lock() with an Unlock() though, or you'll create a deadlock.
*/
/*!
\fn BLocker::BLocker()
\brief Constructor.
\fn BLocker::BLocker()
\brief Constructor.
Create a new BLocker with the default name of <tt>some BLocker</tt>. This
BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually give a
Create a new BLocker with the default name of <tt>some BLocker</tt>. This
BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down which
BLocker object might have caused the problems.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
/*!
\fn BLocker::BLocker(const char* name)
\brief Constructor.
Create a new BLocker with benaphore-style locking.
\param name A NULL-terminated string that contains the name of the semaphore.
Note that the length of the names are limited to B_OS_NAME_LENGTH constant,
which includes the \c \\0 character.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\fn BLocker::BLocker(const char* name)
\brief Constructor.
Create a new BLocker with benaphore-style locking.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
/*!
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
Creates a BLocker with the default name of <tt>some BLocker</tt>.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down which
BLocker object might have caused the problems.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you pass
\c false, the object will completely rely on semaphores for it's
functioning.
\see BLocker(const char* name, bool benaphoreStyle) if you also want to set a
name.
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
Creates a BLocker with the default name of <tt>some BLocker</tt>.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down
which BLocker object might have caused the problems.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you
pass \c false, the object will completely rely on semaphores for
it's functioning.
\see BLocker(const char* name, bool benaphoreStyle) if you also want
to set a name.
*/
/*!
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
\param name A NULL-terminated string that contains the name of the semaphore.
Note that the length of the names are limited to B_OS_NAME_LENGTH constant,
which includes the \c \\0 character.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you pass
\c false, the object will completely rely on semaphores for it's
functioning.
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If
you pass \c false, the object will completely rely on semaphores
for its functioning.
*/
/*!
\fn virtual BLocker::~BLocker()
\brief Destructor.
Release the internal semaphore. Because of this, any pending Lock() calls
from other threads be cancelled. The return code will be \c false for
those calls.
\fn virtual BLocker::~BLocker()
\brief Destructor.
Release the internal semaphore. Because of this, any pending Lock() calls
from other threads be cancelled. The return code will be \c false for
those calls.
*/
/*!
\fn bool BLocker::Lock()
\brief Add a lock request and block on it until we get it.
\retval true Lock acquired succesfully.
\retval false Failed to acquire the lock. Most probable cause is that the
object is deleted. This frees the semaphore and releases the pending Lock()
requests.
\see LockWithTimeout(bigtime_t timeout), Unlock()
\fn bool BLocker::Lock()
\brief Add a lock request and block on it until we get it.
\retval true Lock acquired succesfully.
\retval false Failed to acquire the lock. Most probable cause is that the
object is deleted. This frees the semaphore and releases the
pending Lock() requests.
\see LockWithTimeout(bigtime_t timeout), Unlock()
*/
/*!
\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)
\brief Add a lock request and block until we get it or until it times out.
\param timeout This is a timeout in microseconds (one millionth of a second),
\e relative from now.
\see Lock(), Unlock()
\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)
\brief Add a lock request and block until we get it or until it times out.
\param timeout This is a timeout in microseconds (one millionth of a
second) relative to now.
\see Lock(), Unlock()
*/
/*!
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
*/
/*!
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding the
lock.
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding the
lock.
*/
/*!
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
\retval true The thread from which this method is called from is currently
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
\retval true The thread from which this method is called from is currently
holding the lock.
\retval false The object is unlocked or the lock is held by another thread.
\retval false The object is unlocked or the lock is held by another thread.
*/
/*!
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
*/
/*!
\fn nt32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
\fn nt32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
*/
/*!
\fn sem_id BLocker::Sem(void) const
\brief Return the sem_id of the semaphore this object holds.
\warning Like any other internal objects that the Haiku API might expose,
\fn sem_id BLocker::Sem(void) const
\brief Return the sem_id of the semaphore this object holds.
\warning Like any other internal objects that the Haiku API might expose,
this semaphore id should in general be left alone. You should not use any
of the public low-level semaphore functions on this semaphore, because it
will harm the internal consistency of the object.
docs/user/support/string.dox → docs/user/support/String.dox
+335 -116
View File
File diff suppressed because it is too large Load Diff
docs/user/support/SupportDefs.dox
+352 -151
View File
File diff suppressed because it is too large Load Diff
docs/user/support/TLS.dox
+113 -95
View File
@@ -3,122 +3,140 @@
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk <[email protected]>
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/TLS.h rev 19972
* headers/os/support/TLS.h rev 19972
*/
/*!
\file TLS.h
\ingroup support
\brief Functions to use Thread Local Storage.
The Thread Local Storage API provides convenient methods to transform global
variables in to thread-context sensetive variables. Some applications rely on
global variables as a way of intercommunicating between functions and
objects, but one of your demands might be that the contents of that variable
differs between threads.
The following example demonstrates how an imaginary thread manager that
stores per thread data would function. The constructor of this
\c ThreadManager allocates the TLS variables using tls_allocate(). This only
has to be done once, and not in every spawned thread! Then, every spawned
thread that interacts with this thread manager, should call the
\c InitThread() function. This one associates the supplied thread data with
the TLS index using tls_set(). Each thread can get their associated data with
\c GetCurrentThreadData(), which uses tls_get() to retrieve the associated
thread data at the provided index.
\code
\file TLS.h
\ingroup support
\ingroup libroot
\brief Functions to use Thread Local Storage.
The Thread Local Storage API provides convenient methods to transform global
variables in to thread-context sensitive variables. Some applications rely on
global variables as a way of intercommunicating between functions and
objects, but one of your demands might be that the contents of that variable
differs between threads.
The following example demonstrates how an imaginary thread manager that
stores per thread data would function. The constructor of this
\c ThreadManager allocates the TLS variables using tls_allocate(). This only
has to be done once, and not in every spawned thread! Then, every spawned
thread that interacts with this thread manager, should call the
\c InitThread() function. This one associates the supplied thread data with
the TLS index using tls_set(). Each thread can get their associated data with
\c GetCurrentThreadData(), which uses tls_get() to retrieve the associated
thread data at the provided index.
\code
int32 gThreadName;
int32 gThreadData;
class ThreadManager
{
public:
// General initialisation
ThreadManager() {
gThreadName = tls_allocate();
gThreadStatus = tls_allocate();
};
// Called from the thread entry function
void InitThread(const char *name, void *data) {
tls_set(gThreadName, (void *)name);
tls_set(gThreadData, data);
};
// Can be called from any of the threads. The returned data will be that
// which the thread explicitly set in the InitThread() function
void *GetCurrentThreadData() {
printf("Thread %s asked for its data.\n", (const char*)tls_get(gThreadName));
return tls_get(gThreadData);
};
// General initialisation
ThreadManager() {
gThreadName = tls_allocate();
gThreadStatus = tls_allocate();
};
// Called from the thread entry function
void InitThread(const char *name, void *data) {
tls_set(gThreadName, (void *)name);
tls_set(gThreadData, data);
};
// Can be called from any of the threads. The returned data will be that
// which the thread explicitly set in the InitThread() function
void *GetCurrentThreadData() {
printf("Thread %s asked for its data.\n",
(const char*)tls_get(gThreadName));
return tls_get(gThreadData);
};
};
\endcode
\endcode
\note
-# It is impossible to get data other than from your thread.
-# There is a limit to the number of TLS variables you can allocate. This
limit is define by #TLS_MAX_KEYS, but do realize that you share this
limit with all the libraries your application is linked to.
-# The actual global variables, in the example \c gThreadName and
\c gThreadData, are only indexes. You cannot use these variables to
access data without the TLS API.
\note
-# It is impossible to get data other than from your thread.
-# There is a limit to the number of TLS variables you can allocate. This
limit is define by #TLS_MAX_KEYS, but do realize that you share this
limit with all the libraries your application is linked to.
-# The actual global variables, in the example \c gThreadName and
\c gThreadData, are only indexes. You cannot use these variables to
access data without the TLS API.
*/
/*!
\def TLS_MAX_KEYS
\brief The maximum number of thread local storage variables. This number is
process wide.
*/
/*!
\fn int32 tls_allocate(void)
\brief Allocate a unique index to use for storing variables.
You should only have to do this once to allocate the global index, which you
can reuse in every thread.
\return A unique index to which you can associate per thread data. If we
overrun the maximum number of keys, as defined by #TLS_MAX_KEYS, the
function will return \c B_NO_MEMORY.
\see tls_get(), tls_set(), tls_address()
\def TLS_MAX_KEYS
\brief The maximum number of thread local storage variables. This number is
process wide.
*/
/*!
\fn void *tls_get(int32 index)
\brief Retrieve the data stored for this thread at the provided \a index.
\param index The \a index that you retrieved with tls_allocate().
\return The data you set using tls_set() for this thread, or \c NULL if there
is no data set, or the \a index is invalid.
\see tls_allocate(), tls_set()
*/
/*!
\fn void **tls_address(int32 index)
\brief Retrieve the pointer that refers to the data of this thread at the
\fn int32 tls_allocate(void)
\brief Allocate a unique index to use for storing variables.
You should only have to do this once to allocate the global index, which
you can reuse in every thread.
\return A unique index to which you can associate per thread data. If we
overrun the maximum number of keys, as defined by #TLS_MAX_KEYS,
the function will return \c B_NO_MEMORY.
\sa tls_get()
\sa tls_set()
\sa tls_address()
*/
/*!
\fn void *tls_get(int32 index)
\brief Retrieve the data stored for this thread at the provided \a index.
\param index The \a index that you retrieved with tls_allocate().
\return The data you set using tls_set() for this thread, or \c NULL if there
is no data set, or the \a index is invalid.
\sa tls_allocate()
\sa tls_set()
*/
/*!
\fn void **tls_address(int32 index)
\brief Retrieve the pointer that refers to the data of this thread at the
provided \a index.
You can use this pointer to directly manipulate your thread data.
\param index The \a index that you retrieved with tls_allocate().
\return The pointer to where your thread's data is, or \c NULL if the index
is invalid.
\see tls_allocate(), tls_set(), tls_get()
You can use this pointer to directly manipulate your thread data.
\param index The \a index that you retrieved with tls_allocate().
\return The pointer to where your thread's data is, or \c NULL if the index
is invalid.
\sa tls_allocate()
\sa tls_set()
\sa tls_get()
*/
/*!
\fn void tls_set(int32 index, void *value)
\brief Set the data of this thread at the provided \a index.
It is up to you to make sure the \a index is valid. Any invalid indeces can
lead to unpredicable results.
\param index The \a index that you retrieved with tls_allocate().
\param value The data that should be associated with the index for this
thread.
\see tls_allocate(), tls_get()
\fn void tls_set(int32 index, void *value)
\brief Set the data of this thread at the provided \a index.
It is up to you to make sure the \a index is valid. Any invalid indices can
lead to unpredictable results.
\param index The \a index that you retrieved with tls_allocate().
\param value The data that should be associated with the index for this
thread.
\sa tls_allocate()
\sa tls_get()
*/
docs/user/support/Unarchiver.dox
+46 -21
View File
@@ -1,22 +1,31 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Author:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
* headers/os/support/Archivable.h rev 37751
* src/kits/support/Archivable.cpp rev 37751
*/
/*!
\file Archivable.h
\ingroup support
\ingroup libroot
\brief Contains BUnarchiver class used to simplify the unarchiving of
complicated BArchivable hierarchies.
*/
/*!
\class BUnarchiver
\ingroup support
\ingroup libbe
\brief A class that simplifies the unarchiving of complicated BArchivable
hierarchies.
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
@@ -71,6 +80,8 @@
instantiated.
\param token the object \a token
\returns A status code.
*/
@@ -82,6 +93,8 @@
\param name The archive \a name.
\param index The archive \a index.
\returns A status code.
*/
@@ -90,7 +103,9 @@
\brief Checks whether the object represented by \c token has been
instantiated in this session.
\param token The object \a token
\param token The object \a token.
\returns \c true if instantiated, \c false otherwise
*/
@@ -101,7 +116,9 @@
\param name The archive \a name.
\param index The arcive \a token.
*/
\returns \c true if instantiated, \c false otherwise.
*/
/*!
@@ -123,6 +140,7 @@
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
@@ -141,6 +159,7 @@
BArchiver::GetTokenForArchivable() during archival.
\param object The return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
@@ -170,6 +189,7 @@
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
@@ -189,6 +209,7 @@
like #BMessage::FindData().
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
@@ -210,6 +231,7 @@
retrieved object.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
@@ -230,6 +252,7 @@
adding this object.
\param object Return parameter for the retrieved \a object of type T.
\returns A status code.
\retval B_OK The \a object retrieved was of type T.
\retval B_BAD_TYPE The \a object retrieved was not of type T.
*/
@@ -282,21 +305,22 @@
Here is an example of how you might use this method. Note that you
must still call PrepareArchive(archive) either way.
\code
\code
MyArchivableClas::MyArchivableClass(BMessage* archive)
:
BArchivable(BUnarchiver::PrepareArchive(archive))
:
BArchivable(BUnarchiver::PrepareArchive(archive))
{
BUnarchiver unarchiver(archive);
BUnarchiver unarchiver(archive);
if (BUnarchiver::IsArchiveManaged(archive)) {
// ... calls to FindObject() or GetObject() here ...
} else {
// ... calls to BMessage::FindMessage() here ...
}
if (BUnarchiver::IsArchiveManaged(archive)) {
// ... calls to FindObject() or GetObject() here ...
} else {
// ... calls to BMessage::FindMessage() here ...
}
}
\endcode
\endcode
\returns Whether \a archive was managed by a BArchiver object.
\retval true if \a archive was managed by a BArchiver object.
\retval false otherwise.
*/
@@ -314,14 +338,14 @@ MyArchivableClas::MyArchivableClass(BMessage* archive)
archive constructor of your parent class.
Notice the use of this method in the example provided below.
\code
\code
MyArchivableClas::MyArchivableClas(BMessage* archive)
:
BArchivable(BUnarchiver::PrepareArchive(archive))
:
BArchivable(BUnarchiver::PrepareArchive(archive))
{
// ...
// ...
}
\endcode
\endcode
\param archive The archive you wish to have prepared.
@@ -364,6 +388,7 @@ MyArchivableClas::MyArchivableClas(BMessage* archive)
\param from The #BMessage to instantiate from.
\param object Return parameter for the retrieved object of type T.
\returns A status code.
\retval B_OK The object retrieved was of type T.
\retval B_BAD_TYPE The object retrieved was not of type T.
*/
docs/user/support/parsedate.dox
+148 -137
View File
@@ -1,188 +1,199 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Axel Dörfler
* Authors:
* Axel Dörfler
*
* Corresponds to:
* /trunk/headers/os/support/parsedate.h rev 19972
* headers/os/support/parsedate.h rev 19972
*/
/*!
\file parsedate.h
\ingroup support
\ingroup libroot
\brief Date parsing functions
\file parsedate.h
\ingroup support
\ingroup libroot
\brief Date parsing functions
This is a set a functions for parsing date strings in various formats.
It's mostly tailored for parsing user given data, although originally,
it was developed to parse the date strings found in usenet messages.
This is a set a functions for parsing date strings in various formats.
It's mostly tailored for parsing user given data, although originally,
it was developed to parse the date strings found in usenet messages.
The given date will be parsed relative to the specified time, and using
a predefined set of time/date formats.
The given date will be parsed relative to the specified time, and using
a predefined set of time/date formats.
\par Valid Input Strings
\par Valid Input Strings
The internal formats allow parsedate() to understand a wide range of
input strings. The format list is ought to be compiled from the Date:
line of 80.000 usenet messages.
The internal formats allow parsedate() to understand a wide range of
input strings. The format list is ought to be compiled from the Date:
line of 80.000 usenet messages.
But since this function is also used in end-user applications like the
Tracker's find panel, it's helpful to know what this function accepts
and what not.
But since this function is also used in end-user applications like the
Tracker's find panel, it's helpful to know what this function accepts
and what not.
Here are some examples of input strings that parsedate() will be able
to convert along with some notes:
- "last friday", "this wednesday", "next July"
"last", "next", and "this" refer to the week or year (depending
on the context). So "last friday" means last week's friday.
"This wednesday" is referring to this week's wednesday, no matter
if it has already passed or not.
"Next July" refers to next year's July. All of these dates are
parsed relative to the specified time (usually "now"), and will
be set to the first moment of that time span: "next monday" is
monday, 0:00:00, midnight.
- "now" just returns the time all calculations are relative to.
- "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing,
that is, current time plus exactly 5 minutes.
- "5 weeks" means in 5 weeks from now on.
- "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August
5th, 2003, again at 0:00 midnight.
- "Thursday 3:00" means this week's thursday, at 3 o'clock.
Here are some examples of input strings that parsedate() will be able
to convert along with some notes:
- "last friday", "this wednesday", "next July"
"last", "next", and "this" refer to the week or year (depending
on the context). So "last friday" means last week's friday.
"This wednesday" is referring to this week's wednesday, no matter
if it has already passed or not.
"Next July" refers to next year's July. All of these dates are
parsed relative to the specified time (usually "now"), and will
be set to the first moment of that time span: "next monday" is
monday, 0:00:00, midnight.
- "now" just returns the time all calculations are relative to.
- "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing,
that is, current time plus exactly 5 minutes.
- "5 weeks" means in 5 weeks from now on.
- "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August
5th, 2003, again at 0:00 midnight.
- "Thursday 3:00" means this week's thursday, at 3 o'clock.
\anchor parsedateFormats
\par Format Specifier
\anchor parsedateFormats
\par Format Specifier
While the get_dateformats() function allow you to retrieve the built-in
formats, you can also define your own and use set_dateformats() to let
parsedate() use them in all subsequent calls.
While the get_dateformats() function allow you to retrieve the built-in
formats, you can also define your own and use set_dateformats() to let
parsedate() use them in all subsequent calls.
The following is a list valid format specifiers and their meanings.
The following is a list valid format specifiers and their meanings:
- \b a/A weekday (Sunday, Monday, ...)
- \b d day of month (1-31)
- \b b/B month name (January, February, ...)
- \b month (1-12)
- \b y/Y year
- \b H/I hours (1-24)
- \b M minutes (0-60)
- \b S seconds (0-60)
- \b p meridian (am/pm)
- \b z/Z time zone (i.e. GMT)
- \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc.
- \b - dash or slash
- \b a/A weekday (Sunday, Monday, ...)
- \b d day of month (1-31)
- \b b/B month name (January, February, ...)
- \b month (1-12)
- \b y/Y year
- \b H/I hours (1-24)
- \b M minutes (0-60)
- \b S seconds (0-60)
- \b p meridian (am/pm)
- \b z/Z time zone (i.e. GMT)
- \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc.
- \b - dash or slash
Any of ",.:" is allowed and will be expected in the input string as is.
You can enclose a \b single field with "[]" to mark it as being optional.
A blank stands for white space. No other character is allowed.
An invalid format string won't do any harm, but of course, no input string
will ever match that format.
Any of ",.:" is allowed and will be expected in the input string as is.
You can enclose a \b single field with "[]" to mark it as being optional.
A blank stands for white space. No other character is allowed.
An invalid format string won't do any harm, but of course, no input string
will ever match that format.
For example, "H:M [p]" will match against "21:33", "4:12 am", but not
"30:30 pm" (hours out of range), "15:16 GMT" (this time zone is certainly
not a valid meridian specifier), or "4:66" (minutes out of range).
For example, "H:M [p]" will match against "21:33", "4:12 am", but not
"30:30 pm" (hours out of range), "15:16 GMT" (this time zone is certainly
not a valid meridian specifier), or "4:66" (minutes out of range).
\par Note:
At the time of this writing, the parsedate() functions are not localized and
will only recognize English time specifications following the examples above.
\note At the time of this writing, the parsedate() functions are not
localized and will only recognize English time specifications
following the examples above.
*/
/*!
\def PARSEDATE_RELATIVE_TIME
\brief relative time
The time value was computed relative to the specified time.
/*!
\def PARSEDATE_RELATIVE_TIME
\brief relative time
The time value was computed relative to the specified time.
*/
/*!
\def PARSEDATE_DAY_RELATIVE_TIME
\brief day relative time
The time value was computed relative to the specified time, and it would vary
with every day passed in the specified time.
/*!
\def PARSEDATE_DAY_RELATIVE_TIME
\brief day relative time
The time value was computed relative to the specified time, and it would vary
with every day passed in the specified time.
*/
/*!
\def PARSEDATE_MINUTE_RELATIVE_TIME
\brief minute relative time
The time value was computed relative to the specified time, and it would
vary with every minute passed in the specified time.
/*!
\def PARSEDATE_MINUTE_RELATIVE_TIME
\brief minute relative time
The time value was computed relative to the specified time, and it would
vary with every minute passed in the specified time.
*/
/*!
\def PARSEDATE_INVALID_DATE
\brief invalid date string
This flag will be set if the specified date string could not be parsed
correctly. For example, this may happen if there are some unknown words in
that string.
/*!
\def PARSEDATE_INVALID_DATE
\brief invalid date string
This flag will be set if the specified date string could not be parsed
correctly. For example, this may happen if there are some unknown words in
that string.
*/
/*!
\fn time_t parsedate(const char *dateString, time_t relativeTo)
\brief Parses \a dateString relative to \a relativeTo
\fn time_t parsedate(const char *dateString, time_t relativeTo)
\brief Parses \a dateString relative to \a relativeTo
Parses the given \a dateString relative to the time
specified by \a relativeTo using the internal formats
table.
Parses the given \a dateString relative to the time
specified by \a relativeTo using the internal formats
table.
\param dateString the date that should be parsed, i.e. "next thursday".
\param relativeTo all relative dates will be relative to this time, if -1
\param dateString the date that should be parsed, i.e. "next thursday".
\param relativeTo all relative dates will be relative to this time, if -1
is passed, the current time will be used.
\return the parsed time value or -1 if the \a dateString
\return the parsed time value or -1 if the \a dateString
could not be parsed.
*/
/*!
\fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags)
\brief Parses <span class="var">dateString</span> relative to <span class="var">relativeTo</span>
This does basically the same as parsedate(), but will set the following
flags in <span class="var">_storedFlags</span>:
\htmlonly
<table border=1>
<!-- ToDo: this certainly is a hack -->
<tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr>
<tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_INVALID_DATE</td>
<td>
\endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly
This flag will only be set if the function returns -1.
</td></tr>
</table>
\endhtmlonly
/*!
\fn time_t parsedate_etc(const char *dateString, time_t relativeTo,
int *_storedFlags)
\brief Parses <span class="var">dateString</span> relative to
<span class="var">relativeTo</span>
This does basically the same as parsedate(), but will set the following
flags in <span class="var">_storedFlags</span>:
\htmlonly
<table border=1>
<!-- ToDo: this certainly is a hack -->
<tr><th bgcolor="#eeeeee">Constant</th><th bgcolor="#eeeeee">Meaning</th></tr>
<tr><td class="mdname1">PARSEDATE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_DAY_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_MINUTE_RELATIVE_TIME</td>
<td>\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly
</td></tr>
<tr><td class="mdname1">PARSEDATE_INVALID_DATE</td>
<td>
\endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly
This flag will only be set if the function returns -1.
</td></tr>
</table>
\endhtmlonly
*/
/*!
\fn void set_dateformats(const char *formatTable[])
\brief sets the internal format table for parsedate()
This function let you set the format table which is used by parsedate().
When <span class="var">formatTable</span> is NULL, the standard built-in format table will be set again.
\param formatTable the NULL terminated formats list. This list must stay
/*!
\fn void set_dateformats(const char *formatTable[])
\brief sets the internal format table for parsedate()
This function let you set the format table which is used by parsedate().
When <span class="var">formatTable</span> is NULL, the standard built-in format table will be set again.
\param formatTable the NULL terminated formats list. This list must stay
valid when using parsedate() - it is not copied, but directly used.
\see
\ref parsedateFormats Format!
\see
\ref parsedateFormats Format!
*/
/*!
\fn const char **get_dateformats(void)
\brief returns the internal format table currently used by parsedate()
\fn const char **get_dateformats(void)
\brief returns the internal format table currently used by parsedate()
Returns the internal format table currently used by parsedate() - this is
either a pointer to the built-in one, or one that you have previously
set using set_dateformats().
Returns the internal format table currently used by parsedate() - this is
either a pointer to the built-in one, or one that you have previously
set using set_dateformats().
\see
\ref set_dateformats()
\see
\ref set_dateformats()
*/
docs/user/support/stopwatch.dox
+81 -67
View File
@@ -1,100 +1,114 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation written by:
* Niels Sascha Reedijk <[email protected]>
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/StopWatch.h rev 19972
* /trunk/src/kits/support/StopWatch.cpp rev 14204
* headers/os/support/StopWatch.h rev 19972
* src/kits/support/StopWatch.cpp rev 14204
*/
/*!
\file StopWatch.h
\brief Provides the BStopWatch class.
*/
/*!
\class BStopWatch
\ingroup support
\ingroup libbe
\brief A timer class.
This class provides method to time events. The interface is designed to
behave like a physical stopwatch. It is especially useful for debugging
certain parts of your code, since it can behave like a 'cheap' profiler.
\file StopWatch.h
\ingroup support
\ingroup libroot
\brief Provides the BStopWatch class.
*/
/*!
\fn BStopWatch::BStopWatch(const char *name, bool silent)
\brief Construct a BStopWatch object and starts the timer.
\class BStopWatch
\ingroup support
\ingroup libbe
\brief A timer class.
The constructor creates a clean BStopWatch object. This object
can be given a name. As soon as the object is created, the time
will start ticking away. This class is designed to be usuable as a primitive
profiling tool.
If you are profiling your code with this class, pass true as the
silentparameter. Whenever the object is destroyed, information on
the elapsed time will be streamed to standard output.
\param name The name you want to give this object. You may pass NULL.
\param silent Pass true if you want to use this object as a simple profiler.
This class provides method to time events. The interface is designed to
behave like a physical stopwatch. It is especially useful for debugging
certain parts of your code, since it can behave like a 'cheap' profiler.
*/
/*!
\fn BStopWatch::~BStopWatch()
\brief Destructor.
Destroys the object. If the object was constructed with the parameter
silent set t to false, this destructor will print information on the elapsed
time to standard output.
\fn BStopWatch::BStopWatch(const char *name, bool silent)
\brief Construct a BStopWatch object and starts the timer.
The constructor creates a clean BStopWatch object. This object
can be given a name. As soon as the object is created, the time
will start ticking away. This class is designed to be usuable as a primitive
profiling tool.
If you are profiling your code with this class, pass true as the
\a silent parameter. Whenever the object is destroyed, information on
the elapsed time will be streamed to standard output.
\param name The name you want to give this object. You may pass \c NULL.
\param silent Pass \c true if you want to use this object as a simple
profiler.
*/
/*!
\fn void BStopWatch::Resume()
\brief Resume the timer when it is in a suspended state.
\see Suspend()
\fn BStopWatch::~BStopWatch()
\brief Destructor.
Destroys the object. If the object was constructed with the parameter
silent set t to false, this destructor will print information on the elapsed
time to standard output.
*/
/*!
\fn void BStopWatch::Suspend()
\brief Suspend the timer.
\see Resume()
\fn void BStopWatch::Resume()
\brief Resume the timer when it is in a suspended state.
\see Suspend()
*/
/*!
\fn bigtime_t BStopWatch::Lap()
\brief Start a new lap.
This method sets a lap. With the current implementation you are unable to
actually retrieve the timings of the laps. This is only printed to the
standard output when the object is destroyed. Thus making this tool only
usuable for use when doing some profiling.
\attention Please note that the current implementation is limited to 10 laps.
The value returned is the time that has passed since the timer was started
(and not the time that has passed since the last lap). Any lap call beyond
the 10th lap will overwrite the last value. Note that if the timer is
suspended, nothing happens and the method will return 0.
\fn void BStopWatch::Suspend()
\brief Suspend the timer.
\see Resume()
*/
/*!
\fn bigtime_t BStopWatch::ElapsedTime() const
\brief Get the elapsed time the object has counted.
\return The elapsed time in microseconds.
\fn bigtime_t BStopWatch::Lap()
\brief Start a new lap.
This method sets a lap. With the current implementation you are unable to
actually retrieve the timings of the laps. This is only printed to the
standard output when the object is destroyed. Thus making this tool only
usuable for use when doing some profiling.
\attention Please note that the current implementation is limited to 10 laps.
The value returned is the time that has passed since the timer was started
(and not the time that has passed since the last lap). Any lap call beyond
the 10th lap will overwrite the last value. Note that if the timer is
suspended, nothing happens and the method will return 0.
*/
/*!
\fn void BStopWatch::Reset()
\brief Restart the timer.
Resets the object: it clears the start time, it clears the stored laps and it
restarts the timer.
/*!
\fn bigtime_t BStopWatch::ElapsedTime() const
\brief Get the elapsed time the object has counted.
\return The elapsed time in microseconds.
*/
/*!
\fn const char *BStopWatch::Name() const
\brief Get the name.
\return the name given to the object at creation time.
*/
\fn void BStopWatch::Reset()
\brief Restart the timer.
Resets the object: it clears the start time, it clears the stored laps and it
restarts the timer.
*/
/*!
\fn const char *BStopWatch::Name() const
\brief Get the name.
\return the name given to the object at creation time.
*/
docs/user/support/support_intro.dox
+73 -72
View File
@@ -1,90 +1,91 @@
/*
* Copyright 2007-2010, Haiku, Inc. All Rights Reserved.
* Copyright 2007-2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Nicolas de Leon <[email protected]>
* Authors:
* Nicolas de Leon, [email protected]
* Niels Sascha Reedijk, [email protected]
*/
/*!
\page support_intro Introduction to the Support Kit
\page support_intro Introduction to the Support Kit
The Support Kit provides a handy set of classes that you can use in your
applications. These classes provide:
- \b Thread \b Safety. Haiku can execute multiple threads of an application
in parallel, letting certain parts of an application continue when one part
is stalled, as well as letting an application process multiple pieces of
data at the same time on multicore or multiprocessor systems. However,
there are times when multiple threads desire to work on the same piece of
data at the same time, potentially causing a conflict where variables or
pointers are changed by one thread causing another to execute incorrectly.
To prevent this, Haiku implements a \"locking\" mechanism, allowing one
thread to \"lock out\" other threads from executing code that might modify
the same data.
- \b Archiving \b and \b IO. These classes allow a programmer to convert
objects into a form that can more easily be transferred to other
applications or stored to disk, as well as performing basic input and
output operations.
- \b Memory \b Allocation. This class allows a programmer to hand off some of
the duties of memory accounting and management.
- \b Common \b Datatypes. To avoid unnecessary duplication of code and to
make life easier for programmers, Haiku includes classes that handle
management of ordered lists and strings.
There are also a number of utility functions to time actions, play system
alert sounds, compare strings, and atomically manipulate integers. Have a
look at the overview, or go straight to the complete
\link support list of components \endlink of this kit.
The Support Kit provides a handy set of classes that you can use in your
applications. These classes provide:
- \b Thread \b Safety. Haiku can execute multiple threads of an application
in parallel, letting certain parts of an application continue when one part
is stalled, as well as letting an application process multiple pieces of
data at the same time on multicore or multiprocessor systems. However,
there are times when multiple threads desire to work on the same piece of
data at the same time, potentially causing a conflict where variables or
pointers are changed by one thread causing another to execute incorrectly.
To prevent this, Haiku implements a \"locking\" mechanism, allowing one
thread to \"lock out\" other threads from executing code that might modify
the same data.
- \b Archiving \b and \b IO. These classes allow a programmer to convert
objects into a form that can more easily be transferred to other
applications or stored to disk, as well as performing basic input and
output operations.
- \b Memory \b Allocation. This class allows a programmer to hand off some of
the duties of memory accounting and management.
- \b Common \b Datatypes. To avoid unnecessary duplication of code and to
make life easier for programmers, Haiku includes classes that handle
management of ordered lists and strings.
\section Overview
- Thread Safety:
- BLocker provides a semaphore-like locking mechanism allowing for
recursive locks.
- BAutolock provides a simple method of automatically removing a lock
when a function ends.
- \ref TLS.h "Thread Local Storage" allows a global variable\'s content to
be sensitive to thread context.
- Archiving and IO:
- BArchivable provides an interface for \"archiving\" objects so that they
may be sent to other applications where an identical copy will be
recreated.
- BArchiver simplifies archiving of BArchivable hierarchies.
- BUnarchiver simplifies unarchiving hierarchies that have been archived
using BArchiver.
- BFlattenable provides an interface for \"flattening\" objects so that
they may be easily stored to disk.
- BDataIO provides an interface for generalized read/write streams.
- BPositionIO extends BDataIO to allow seeking within the data.
- BBufferIO creates a buffer and attaches it to a BPositionIO stream,
allowing for reduced load on the underlying stream.
- BMemoryIO allows operation on an already-existing buffer.
- BMallocIO creates and allows operation on a buffer.
- Memory Allocation:
- BBlockCache allows an application to allocate a \"pool\" of memory blocks
that the application can fetch and dispose of as it pleases, letting the
application make only a few large memory allocations, instead of many
expensive small allocations.
- Common Datatypes:
- BList allows simple ordered lists and provides common access,
modification, and comparison functions.
- BString allows strings and provides common access, modification, and
comparison functions.
- BStopWatch allows an application to measure the time an action takes.
- \ref support_globals "Global functions"
- \ref TypeConstants.h "Common types and constants"
- Error codes for all kits
There are also a number of utility functions to time actions, play system
alert sounds, compare strings, and atomically manipulate integers. Have a
look at the overview, or go straight to the complete
\link support list of components \endlink of this kit.
\section Overview
- Thread Safety:
- BLocker provides a semaphore-like locking mechanism allowing for
recursive locks.
- BAutolock provides a simple method of automatically removing a lock
when a function ends.
- \ref TLS.h "Thread Local Storage" allows a global variable\'s content to
be sensitive to thread context.
- Archiving and IO:
- BArchivable provides an interface for \"archiving\" objects so that they
may be sent to other applications where an identical copy will be
recreated.
- BArchiver simplifies archiving of BArchivable hierarchies.
- BUnarchiver simplifies unarchiving hierarchies that have been archived
using BArchiver.
- BFlattenable provides an interface for \"flattening\" objects so that
they may be easily stored to disk.
- BDataIO provides an interface for generalized read/write streams.
- BPositionIO extends BDataIO to allow seeking within the data.
- BBufferIO creates a buffer and attaches it to a BPositionIO stream,
allowing for reduced load on the underlying stream.
- BMemoryIO allows operation on an already-existing buffer.
- BMallocIO creates and allows operation on a buffer.
- Memory Allocation:
- BBlockCache allows an application to allocate a \"pool\" of memory blocks
that the application can fetch and dispose of as it pleases, letting the
application make only a few large memory allocations, instead of many
expensive small allocations.
- Common Datatypes:
- BList allows simple ordered lists and provides common access,
modification, and comparison functions.
- BString allows strings and provides common access, modification, and
comparison functions.
- BStopWatch allows an application to measure the time an action takes.
- \ref support_globals "Global functions"
- \ref TypeConstants.h "Common types and constants"
- Error codes for all kits
*/
// Short listing of documents that belong to this module so that people can
// find these from the module overview.
// This should become standardized in Doxygen though. There is an item on
// the todo list on this.
/*!
\addtogroup support
\addtogroup support
For a better overview, have a look at \ref support_intro .
For a better overview, have a look at \ref support_intro .
*/
docs/user/support/syslog.dox
+263 -206
View File
@@ -1,293 +1,350 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation written by:
* Axel Dörfler
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Axel Dörfler
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/posix/syslog.h rev 6684
* headers/posix/syslog.h rev 6684
*/
/*!
\file syslog.h
\ingroup support
\ingroup libroot
\brief System logging capabilities
The functions described here are interacting with the syslog_daemon, a server
that provides the system logging capabilities.
The log can be found in /var/log/syslog.
*/
/*!
\fn void closelog(void)
\brief Closes the current log session
*/
/*!
\fn void openlog(const char *ident, int options, int facility)
\brief Starts a log session, and sets some output options
Like openlog_thread() this function defines the log session in thread context; the
global options set by openlog_team() are not affected by this function.
*/
/*!
\fn int setlogmask(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\fn void syslog(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn void closelog_team(void)
\brief Closes the log
*/
/*!
\fn void openlog_team(const char *ident, int logopt, int facility)
\brief Starts a log session, and sets some output options
This function defines the team-wide logging options. Thread local sessions
started with openlog() or openlog_thread() will inherit the options of the
global session.
*/
/*!
\fn void log_team(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn int setlogmask_team(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\fn void closelog_thread(void)
\brief Closes the log
*/
/*!
\fn void openlog_thread(const char *ident, int logopt, int facility)
\brief Starts a log session, and sets some output options
*/
/*!
\fn void log_thread(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn int setlogmask_thread(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\name Options for openlog()
\file syslog.h
\ingroup support
\ingroup libroot
\brief System logging capabilities
The functions described here are interacting with the syslog_daemon, a server
that provides the system logging capabilities.
The log can be found in /var/log/syslog.
*/
/*!
\fn void closelog(void)
\brief Closes the current log session
*/
/*!
\fn void openlog(const char *ident, int options, int facility)
\brief Starts a log session, and sets some output options
Like openlog_thread() this function defines the log session in thread context; the
global options set by openlog_team() are not affected by this function.
*/
/*!
\fn int setlogmask(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\fn void syslog(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn void closelog_team(void)
\brief Closes the log
*/
/*!
\fn void openlog_team(const char *ident, int logopt, int facility)
\brief Starts a log session, and sets some output options
This function defines the team-wide logging options. Thread local sessions
started with openlog() or openlog_thread() will inherit the options of the
global session.
*/
/*!
\fn void log_team(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn int setlogmask_team(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\fn void closelog_thread(void)
\brief Closes the log
*/
/*!
\fn void openlog_thread(const char *ident, int logopt, int facility)
\brief Starts a log session, and sets some output options
*/
/*!
\fn void log_thread(int priority, const char *message, ...)
\brief sends a message to the system log
*/
/*!
\fn int setlogmask_thread(int priorityMask)
\brief sets the logging priority mask
*/
/*!
\name Options for openlog()
*/
//! @{
/*!
\def LOG_PID
\brief Log the process (thread/team) ID with each message
/*!
\def LOG_PID
\brief Log the process (thread/team) ID with each message
*/
/*!
\def LOG_CONS
\brief Log to the system console on error
/*!
\def LOG_CONS
\brief Log to the system console on error
*/
/*!
\def LOG_ODELAY
\brief Delay open until syslog() is called
/*!
\def LOG_ODELAY
\brief Delay open until syslog() is called
*/
/*!
\def LOG_NDELAY
\brief Connect to the syslog daemon immediately
/*!
\def LOG_NDELAY
\brief Connect to the syslog daemon immediately
*/
/*!
\def LOG_SERIAL
\brief Dump to serial output as well.
\attention This is not yet implemented
/*!
\def LOG_SERIAL
\brief Dump to serial output as well.
\attention This is not yet implemented
*/
/*!
\def LOG_PERROR
\brief Dump to stderr as well
/*!
\def LOG_PERROR
\brief Dump to stderr as well
*/
/*!
\def LOG_NOWAIT
\brief Do not wait for child processes
/*!
\def LOG_NOWAIT
\brief Do not wait for child processes
*/
//! @}
/*!
\name Facilities for openlog()
/*! \name Facilities for openlog()
*/
//! @{
/*!
\def LOG_KERN
\brief Reserved for messages generated by the kernel.
*/
/*!
\def LOG_USER
\brief Reserved for messages generated by user processes.
*/
/*!
\def LOG_MAIL
\brief Standard (?) POSIX facility for messages by the mailing daemon.
\def LOG_KERN
\brief Reserved for messages generated by the kernel.
*/
/*!
\def LOG_DAEMON
\brief Standard POSIX (?) facility for messages by daemons (and Haiku servers).
*/
/*!
\def LOG_AUTH
\brief Standard POSIX facility(?) for messages by the authentication services.
*/
/*!
\def LOG_SYSLOG
\brief Reserved for messages generated by the syslog daemon.
*/
/*!
\def LOG_LPR
\brief Reserved for messages generated by the UNIX lpr printing tool.
*/
/*!
\def LOG_NEWS
\brief Reserved for messages generated by something UNIXy that does something with NEWS.
*/
/*!
\def LOG_UUCP
\brief Reserved for messages generated by UUCP
\def LOG_USER
\brief Reserved for messages generated by user processes.
*/
/*!
\def LOG_CRON
\brief Reserved for messages generated by the CRON daemon.
\def LOG_MAIL
\brief Standard (?) POSIX facility for messages by the mailing daemon.
*/
/*!
\def LOG_AUTHPRIV
\brief Reserved for private (?) messages that relate to authentication.
*/
/*!
\def LOG_LOCAL0
\brief Use this for local use.
\def LOG_DAEMON
\brief Standard POSIX (?) facility for messages by daemons (and Haiku servers).
*/
/*!
\def LOG_LOCAL1
\brief Use this for local use.
\def LOG_AUTH
\brief Standard POSIX facility(?) for messages by the authentication services.
*/
/*!
\def LOG_LOCAL2
\brief Use this for local use.
/*!
\def LOG_SYSLOG
\brief Reserved for messages generated by the syslog daemon.
*/
/*!
\def LOG_LOCAL3
\brief Use this for local use.
*/
/*!
\def LOG_LOCAL4
\brief Use this for local use.
\def LOG_LPR
\brief Reserved for messages generated by the UNIX lpr printing tool.
*/
/*!
\def LOG_LOCAL5
\brief Use this for local use.
/*!
\def LOG_NEWS
\brief Reserved for messages generated by something UNIXy that does something with NEWS.
*/
/*!
\def LOG_LOCAL6
\brief Use this for local use.
/*!
\def LOG_UUCP
\brief Reserved for messages generated by UUCP
*/
/*!
\def LOG_LOCAL7
\brief Use this for local use.
/*!
\def LOG_CRON
\brief Reserved for messages generated by the CRON daemon.
*/
/*!
\def LOG_AUTHPRIV
\brief Reserved for private (?) messages that relate to authentication.
*/
/*!
\def LOG_LOCAL0
\brief For local use.
*/
/*!
\def LOG_LOCAL1
\brief For local use.
*/
/*!
\def LOG_LOCAL2
\brief For local use.
*/
/*!
\def LOG_LOCAL3
\brief For local use.
*/
/*!
\def LOG_LOCAL4
\brief For local use.
*/
/*!
\def LOG_LOCAL5
\brief For local use.
*/
/*!
\def LOG_LOCAL6
\brief For local use.
*/
/*!
\def LOG_LOCAL7
\brief For local use.
*/
//! @}
/*!
\name Priorities for syslog(), log_team() and log_thread()
/*! \name Priorities for syslog(), log_team() and log_thread()
*/
//! @{
/*!
\def LOG_EMERG
\brief A panic condition
/*!
\def LOG_EMERG
\brief A panic condition
*/
/*!
\def LOG_PANIC
\brief An alias for LOG_EMERG
/*!
\def LOG_PANIC
\brief An alias for LOG_EMERG
*/
/*!
\def LOG_ALERT
\brief A condition to that should be corrected immediately
/*!
\def LOG_ALERT
\brief A condition to that should be corrected immediately
*/
/*!
\def LOG_CRIT
\brief Critical conditions like hard drive errors
/*!
\def LOG_CRIT
\brief Critical conditions like hard drive errors
*/
/*!
\def LOG_ERR
\brief Errors
*/
/*!
\def LOG_WARNING
\brief Warnings
\def LOG_ERR
\brief Errors
*/
/*!
\def LOG_NOTICE
\brief Notices, instructions on how to use certain configuration options.
/*!
\def LOG_WARNING
\brief Warnings
*/
/*!
\def LOG_INFO
\brief Information, like versions and so.
/*!
\def LOG_NOTICE
\brief Notices, instructions on how to use certain configuration options.
*/
/*!
\def LOG_INFO
\brief Information, like versions and so.
*/
/*!
\def LOG_DEBUG
\brief Debug information.
*/
/*!
\def LOG_DEBUG
\brief Debug information.
*/\
//! @}
/*!
\def LOG_MASK
\brief Converts a priority definition for use in setlogmask()
*/
/*!
\def LOG_MASK
\brief Converts a priority definition for use in setlogmask()
*/
docs/user/support/typeconstants.dox
+150 -108
View File
@@ -1,185 +1,227 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/TypeConstants.h rev 20212
* headers/os/support/TypeConstants.h rev 20212
*/
/*!
\file TypeConstants.h
\ingroup support
\brief Represents typecodes that are used in various part of the Haiku API.
The type codes all refer to a specified type, except one. B_ANY_TYPE can
refer to literaly any type. This type could be used in case you send or receive
data of which you don't know the type, but you want to send or receive it
anyway.
*/
/*!
\var B_ANY_TYPE
\brief General type when the exact contents is not yet known.
\file TypeConstants.h
\ingroup support
\ingroup libroot
\brief Represents typecodes that are used in various part of the Haiku API.
The type codes all refer to a specified type, except one. B_ANY_TYPE can
refer to literaly any type. This type could be used in case you send or receive
data of which you don't know the type, but you want to send or receive it
anyway.
*/
/*!
\var B_ATOM_TYPE
\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku.
*/
/*!
\var B_ATOMREF_TYPE
\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku.
\var B_ANY_TYPE
\brief General type when the exact contents is not yet known.
*/
/*!
\var B_BOOL_TYPE
\brief Boolean value.
*/
/*!
\var B_CHAR_TYPE
\brief Represents the \c char type.
\var B_ATOM_TYPE
\brief Reference to a BAtomic class that was going to be in BeOS R6.
Unused in Haiku.
*/
/*!
\var B_COLOR_8_BIT_TYPE
\brief Represents a one-byte colour.
*/
/*!
\var B_DOUBLE_TYPE
\brief Represents the \c double type.
\var B_ATOMREF_TYPE
\brief Reference to a BAtomic class that was going to be in BeOS R6.
Unused in Haiku.
*/
/*!
\var B_FLOAT_TYPE
\brief Represents the \c float type.
*/
/*!
\var B_GRAYSCALE_8_BIT_TYPE
\brief Represents a byte-long grayscale value.
\var B_BOOL_TYPE
\brief Boolean value.
*/
/*!
\var B_INT16_TYPE
\brief Represents a \c short type.
*/
/*!
\var B_INT32_TYPE
\brief Represents a \c long type.
\var B_CHAR_TYPE
\brief Represents the \c char type.
*/
/*!
\var B_INT64_TYPE
\brief Represents a \c long \c long type.
*/
/*!
\var B_INT8_TYPE
\brief Represents a \c char type used for integer storage.
\var B_COLOR_8_BIT_TYPE
\brief Represents a one-byte color.
*/
/*!
\var B_LARGE_ICON_TYPE
\brief Represents a large icon.
*/
/*!
\var B_MEDIA_PARAMETER_GROUP_TYPE
\brief Represents the BParameterGroup type from the media kit.
\var B_DOUBLE_TYPE
\brief Represents the \c double type.
*/
/*!
\var B_MEDIA_PARAMETER_TYPE
\brief Represents the BParameter type from the media kit.
*/
/*!
\var B_MEDIA_PARAMETER_WEB_TYPE
\brief Represents the BParameterWeb type from the media kit.
\var B_FLOAT_TYPE
\brief Represents the \c float type.
*/
/*!
\var B_MESSAGE_TYPE
\brief Represents a BMessage type.
*/
/*!
\var B_MESSENGER_TYPE
\brief Represents a BMessenger type.
\var B_GRAYSCALE_8_BIT_TYPE
\brief Represents a byte-long grayscale value.
*/
/*!
\var B_INT16_TYPE
\brief Represents a \c short type.
*/
/*!
\var B_INT32_TYPE
\brief Represents a \c long type.
*/
/*!
\var B_INT64_TYPE
\brief Represents a \c long \c long type.
*/
/*!
\var B_INT8_TYPE
\brief Represents a \c char type used for integer storage.
*/
/*!
\var B_LARGE_ICON_TYPE
\brief Represents a large icon.
*/
/*!
\var B_MEDIA_PARAMETER_GROUP_TYPE
\brief Represents the BParameterGroup type from the media kit.
*/
/*!
\var B_MEDIA_PARAMETER_TYPE
\brief Represents the BParameter type from the media kit.
*/
/*!
\var B_MEDIA_PARAMETER_WEB_TYPE
\brief Represents the BParameterWeb type from the media kit.
*/
/*!
\var B_MESSAGE_TYPE
\brief Represents a BMessage type.
*/
/*!
\var B_MESSENGER_TYPE
\brief Represents a BMessenger type.
*/
// Todo: the rest of the types
/*!
\name System-wide MIME types for handling URLs
/*!
\name System-wide MIME types for handling URLs
*/
//! @{
/*!
\var B_URL_HTTP
\brief application/x-vnd.Be.URL.http
*/
/*!
\var B_URL_HTTPS
\brief application/x-vnd.Be.URL.https
\var B_URL_HTTP
\brief application/x-vnd.Be.URL.http
*/
/*!
\var B_URL_FTP
\brief application/x-vnd.Be.URL.ftp
*/
/*!
\var B_URL_GOPHER
\brief application/x-vnd.Be.URL.gopher
\var B_URL_HTTPS
\brief application/x-vnd.Be.URL.https
*/
/*!
\var B_URL_MAILTO
\brief application/x-vnd.Be.URL.mailto
*/
/*!
\var B_URL_NEWS
\brief application/x-vnd.Be.URL.news
\var B_URL_FTP
\brief application/x-vnd.Be.URL.ftp
*/
/*!
\var B_URL_NNTP
\brief application/x-vnd.Be.URL.nntp
*/
/*!
\var B_URL_TELNET
\brief application/x-vnd.Be.URL.telnet
\var B_URL_GOPHER
\brief application/x-vnd.Be.URL.gopher
*/
/*!
\var B_URL_RLOGIN
\brief application/x-vnd.Be.URL.rlogin
*/
/*!
\var B_URL_TN3270
\brief application/x-vnd.Be.URL.tn3270
\var B_URL_MAILTO
\brief application/x-vnd.Be.URL.mailto
*/
/*!
\var B_URL_WAIS
\brief application/x-vnd.Be.URL.wais
*/
/*!
\var B_URL_FILE
\brief application/x-vnd.Be.URL.file
\var B_URL_NEWS
\brief application/x-vnd.Be.URL.news
*/
/*!
\var B_URL_NNTP
\brief application/x-vnd.Be.URL.nntp
*/
/*!
\var B_URL_TELNET
\brief application/x-vnd.Be.URL.telnet
*/
/*!
\var B_URL_RLOGIN
\brief application/x-vnd.Be.URL.rlogin
*/
/*!
\var B_URL_TN3270
\brief application/x-vnd.Be.URL.tn3270
*/
/*!
\var B_URL_WAIS
\brief application/x-vnd.Be.URL.wais
*/
/*!
\var B_URL_FILE
\brief application/x-vnd.Be.URL.file
*/
//! @}