From 89e18a513c88a244eadb707a1a036d705692d16b Mon Sep 17 00:00:00 2001 From: Niels Sascha Reedijk Date: Fri, 2 Mar 2007 13:36:32 +0000 Subject: [PATCH] * Take a document on compatibility from the Haiku website (experimenting with pages) - Originally written by Ingo and updated by others, I have permission from Ingo. * book.dox Rework a bit of the structure * midi2/support Separate the overview (or Introduction) from the list of elements in a module. * support Wrote initial documentation for Beep/BufferIO/DataIO * Stub for article on archiving. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@20307 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- docs/user/Doxyfile | 6 +- docs/user/book.dox | 11 +- docs/user/compatibility.dox | 45 +++ docs/user/midi2/midi2intro.dox | 21 +- docs/user/midi2/midiendpoint.dox | 2 +- docs/user/midi2/midiroster.dox | 6 + docs/user/support/Autolock.dox | 6 +- docs/user/support/Beep.dox | 32 ++ docs/user/support/BufferIO.dox | 163 ++++++++++ docs/user/support/DataIO.dox | 405 ++++++++++++++++++++++++ docs/user/support/string.dox | 54 +++- docs/user/support/support_archiving.dox | 7 + docs/user/support/support_intro.dox | 22 +- 13 files changed, 745 insertions(+), 35 deletions(-) create mode 100644 docs/user/compatibility.dox create mode 100644 docs/user/support/Beep.dox create mode 100644 docs/user/support/BufferIO.dox create mode 100644 docs/user/support/DataIO.dox create mode 100644 docs/user/support/support_archiving.dox diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 7c1e650149..8e1411724a 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -100,7 +100,7 @@ ALWAYS_DETAILED_SEC = NO # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. -INLINE_INHERITED_MEMB = NO +INLINE_INHERITED_MEMB = YES # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full # path before files name in the file list and in the header files. If set @@ -1022,7 +1022,9 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +# Beep.h requires __cplusplus to be defined. + +PREDEFINED = __cplusplus # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/docs/user/book.dox b/docs/user/book.dox index 929567f195..944f511cc0 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -4,14 +4,21 @@ \section kits Kits and Servers - \ref midi1 -- \ref midi2 -- \ref support +- \ref midi2 | \link midi2_intro \em Introduction \endlink +- \ref support | \link support_intro \em Introduction \endlink + +\section notes General Notes and Information +- \ref compatibility */ +// Define main kits + /*! \defgroup midi2 MIDI 2 Kit +\brief API for producing and consuming MIDI events. \defgroup libmidi2 (libmidi2.so) \defgroup support Support Kit +\brief Collection of utility classes that are used throughout the API. \defgroup libbe (libbe.so) \defgroup libroot (libroot.so) */ diff --git a/docs/user/compatibility.dox b/docs/user/compatibility.dox new file mode 100644 index 0000000000..84c48723c7 --- /dev/null +++ b/docs/user/compatibility.dox @@ -0,0 +1,45 @@ +/*! +\page compatibility Application Level API Incompatibilities with BeOS + +\author Ingo Weinhold + +Haiku R1 (x86) was designed and is being implemented to be binary and source +compatible with applications written for BeOS R5 (x86) to a large extent, but +not the other way around. In some cases we deliberately broke source +compatibility while at the same time maintaining binary compatibility. Here are +some specific examples: + +- The \c "be" header path is gone - it's called \c "os" in Haiku; since it is + always part of the default header search path anyway, you can always just + remove it to let your software compile on both platforms, ie. replace: +\code +#include +\endcode + with: +\code +#include +\endcode + or rather use the preferred method of omitting the first part and use: +\code +#include +\endcode + +- BeOS contains a deprecated \c add-ons/TrackerAddons.h header, and a + header called \c add-ons/TrackerAddOns.h - Haiku only contains the + latter. +- Likewise, you'll find \c support/byteorder.h and \c support/ByteOrder.h + in BeOS; Haiku only has ByteOrder.h. +- If you have subclassed BString and if you are using its \c _privateData + member, you might notice that it has been renamed to \link BString::fPrivateData + fPrivateData \endlink. However, it's use is deprecated, and it might even be + made private in the future. +- The undocumented functions defined in the headers are not implemented. +- The private Device Map API (used by OpenTracker) has been replaced by a + different API (Disk Device API). +- The application debugging interface is conceptually similar, but nevertheless + source and binary incompatible. +- The file system API has changed; file systems that worked on BeOS will no + longer work on Haiku. +- In several places we also dropped compatibility support for older BeOS + versions (PR2, R3, R4), which BeOS R5 still featured. +*/ \ No newline at end of file diff --git a/docs/user/midi2/midi2intro.dox b/docs/user/midi2/midi2intro.dox index 3d6eaef722..4243e955ab 100644 --- a/docs/user/midi2/midi2intro.dox +++ b/docs/user/midi2/midi2intro.dox @@ -1,16 +1,12 @@ /*! -\ingroup midi2 -*/ - -/*\{*/ - -/*! -\page midi2intro +\page midi2_intro Introduction to the MIDI2 Kit The Midi Kit is the API that implements support for generating, processing, and playing music in MIDI format. MIDI, which stands for 'Musical Instrument Digital Interface', is a well-established -standard for representing and communicating musical data. +standard for representing and communicating musical data. This document serves +as an overview. If you would like to see all the components, please look at +\link midi2 the list with classes \endlink . \section midi2twokits The two kits @@ -273,7 +269,7 @@ event as quickly as possible and be done with it. Do not \section midi2apidiffs API differences -As far as the end user is concerned, the OpenBeOS Midi Kit is mostly the same +As far as the end user is concerned, the Haiku Midi Kit is mostly the same as the BeOS R5 kits, although there are a few small differences in the API (mostly bug fixes): @@ -308,4 +304,9 @@ Information about MIDI in general: */ -/*\}*/ +/*! +\addtogroup midi2 + +Please have a look at the \link midi2_intro introduction \endlink for a more +comprehensive overview on how everything ties together. +*/ diff --git a/docs/user/midi2/midiendpoint.dox b/docs/user/midi2/midiendpoint.dox index c5575839cd..8d69071e24 100644 --- a/docs/user/midi2/midiendpoint.dox +++ b/docs/user/midi2/midiendpoint.dox @@ -1,5 +1,5 @@ /*! -\class BMidiEndpoint MidiEndpoint.h +\class BMidiEndpoint \ingroup midi2 \ingroup libmidi2 \brief Base class for all MIDI endpoints diff --git a/docs/user/midi2/midiroster.dox b/docs/user/midi2/midiroster.dox index 502ef46325..c03c5fda0d 100644 --- a/docs/user/midi2/midiroster.dox +++ b/docs/user/midi2/midiroster.dox @@ -1,3 +1,9 @@ +/*! +\var B_MIDI_EVENT +\ingroup midi2 +\brief BMessage identifier of MIDI messages. +*/ + /*! \class BMidiRoster MidiRoster.h \ingroup midi2 diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox index b93d7b2344..31e45b5192 100644 --- a/docs/user/support/Autolock.dox +++ b/docs/user/support/Autolock.dox @@ -64,7 +64,7 @@ Receiver::HandleCall(Call *call) 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 written. +exit from the function is properly unlocked. */ /*! @@ -96,8 +96,8 @@ 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 might get this behaviour, you can use this method to help you -protect yourself from it. +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. */ diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox new file mode 100644 index 0000000000..15cf1929b4 --- /dev/null +++ b/docs/user/support/Beep.dox @@ -0,0 +1,32 @@ +/*! +\file Beep.h +\brief Functions to generate sounds from the computer. +*/ + +/*! +\addtogroup support_globals +@{ +*/ + +/*! +\fn status_t beep() +\brief TODO: Not implemented nor documented. + +From Beep.h and in libbe.so. +*/ + +/*! +\fn status_t system_beep(const char* eventName) +\brief TODO: Not implemented nor documented. + +From Beep.h and in libbe.so. +*/ + +/*! +\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0) +\brief TODO: Not implemented nor documented. + +From Beep.h and in libbe.so. +*/ + +//! @} \ No newline at end of file diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox new file mode 100644 index 0000000000..bdf858862f --- /dev/null +++ b/docs/user/support/BufferIO.dox @@ -0,0 +1,163 @@ +/*! +\file BufferIO.h +\brief Provides the BBufferIO class. +*/ + +/*! +\class BBufferIO +\ingroup support +\ingroup libbe +\brief A buffered adapter for BPositionIO objects. +\author Stefano Ceccherini \ + +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 +\c 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. +*/ + +/*! +\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. + +\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. +*/ + + +/*! +\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. +*/ + +/*! +\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). + + \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 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. +\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 size_t BBufferIO::BufferSize() const +\brief Return the size of the internal buffer. +\return The size of the buffer allocated by the object. +*/ + +/*! +\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. +\sa 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. +*/ diff --git a/docs/user/support/DataIO.dox b/docs/user/support/DataIO.dox new file mode 100644 index 0000000000..1d2d25530d --- /dev/null +++ b/docs/user/support/DataIO.dox @@ -0,0 +1,405 @@ +/*! +\file DataIO.h +\brief Provides abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes. + +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. +*/ + +//////////// BDataIO + +/*! +\class BDataIO +\ingroup support +\ingroup libbe +\brief Abstract interface for objects that provides 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. + +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. +*/ + +/*! +\fn BDataIO::BDataIO() +\brief This constructor 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 + 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 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. + +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. + +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 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. +*/ + +/*! +\fn BPositionIO::BPositionIO() +\brief This constructor 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::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. + +Your implementation should copy data from the position indicated by \c position +into the \c buffer with the maximum size of \c size. + +\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. + +Your implementation should copy data from \c buffer to the position indicated +by \c buffer with the maximum size of \c size. + +\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. + +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: + - \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. +*/ + +/*! +\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. + +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 + error code. +*/ + +/*! +\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. + +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. +\sa Seek() +*/ + +//////////// BMemoryIO +/*! +\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 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. +*/ + +/*! +\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. +\sa 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. +\sa BMemoryIO(void *buffer, size_t length) for a read-write implementation. +*/ + +/*! +\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 \c 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 to 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. Possibilities: + - \c SEEK_SET The cursor is set to \c 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 + \c position added to it. +\return The new position. +*/ + +/*! +\fn off_t BMemoryIO::Position() const +\brief Return the current position. +*/ + +/*! +\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 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. +*/ + +//////////// BMallocIO +/*! +\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. + +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. + +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. +\sa SetBlockSize() +*/ + +/*! +\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 + the provided \c 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 \c 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: + - \c SEEK_SET The cursor is set to \c 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 + \c position added to it. +\return The new position. +*/ + +/*! +\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. + +This method changes the size of the current buffer. If \c 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. +*/ + +/*! +\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. + +\param blockSize The new block size. +*/ + +/*! +\fn const void *BMallocIO::Buffer() const +\brief Return a pointer to the internal buffer. + +As with any pointer to internal buffers you can retrieve with the Haiku API, +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. + +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. +*/ + diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox index f1b5bf455b..1cd57f74ff 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/string.dox @@ -28,6 +28,8 @@ takes care to allocate and free memory for you, so it will always be \var char* BString::fPrivateData \brief BString's storage for data +This member is deprecated and might even go \c private in future releases. + If you are planning to derive from this object and you want to manipulate the raw string data, please have a look at LockBuffer() and UnlockBuffer(). */ @@ -1309,38 +1311,56 @@ These methods may be slower than sprintf(), but they are overflow safe. /*! -\fn bool operator<(const char *str, const BString &string) -\brief Lexographically compare if \c str is less than a given BString. +\fn bool operator<(const char *a, const BString &b) +\brief Lexographically compare if \c a is less than a given BString. + +From String.h and in libbe.so. + \sa BString::operator<(const char *string) const */ /*! -\fn bool operator<=(const char *str, const BString &string) -\brief Lexographically compare if \c str is less than or equal to a given BString. +\fn bool operator<=(const char *a, const BString &b) +\brief Lexographically compare if \c a is less than or equal to a given BString. + +From String.h and in libbe.so. + \sa BString::operator<=(const char *string) const */ /*! -\fn bool operator==(const char *str, const BString &string) -\brief Lexographically compare if \c str is equal to a given BString. +\fn bool operator==(const char *a, const BString &b) +\brief Lexographically compare if \c a is equal to a given BString. + +From String.h and in libbe.so. + \sa BString::operator==(const char *string) const */ /*! -\fn bool operator>(const char *str, const BString &string) -\brief Lexographically compare if \c str is more than a given BString. +\fn bool operator>(const char *a, const BString &b) +\brief Lexographically compare if \c a is more than a given BString. + +From String.h and in libbe.so. + \sa BString::operator>(const char *string) const */ /*! -\fn bool operator>=(const char *str, const BString &string) -\brief Lexographically compare if \c str is more than or equal to a given BString. +\fn bool operator>=(const char *a, const BString &b) +\brief Lexographically compare if \c a is more than or equal to a given BString. + +From String.h and in libbe.so. + \sa BString::operator>=(const char *string) const */ /*! -\fn bool operator!=(const char *str, const BString &string) -\brief Lexographically compare if \c str is not equal to given BString. +\fn bool operator!=(const char *a, const BString &b) +\brief Lexographically compare if \c a is not equal to given BString. + +From String.h and in libbe.so. + \sa BString::operator!=(const char *string) const */ @@ -1351,6 +1371,8 @@ These methods may be slower than sprintf(), but they are overflow safe. This function is useful if you need a global compare function to feed to BList::SortItems() for example. +From String.h and in libbe.so. + \sa BString::Compare(const BString &string) const */ @@ -1361,6 +1383,8 @@ BList::SortItems() for example. This function is useful if you need a global compare function to feed to BList::SortItems() for example. +From String.h and in libbe.so. + \sa BString::Compare(const BString &string) const */ @@ -1371,16 +1395,20 @@ BList::SortItems() for example. This function is useful if you need a global compare function to feed to BList::SortItems() for example. +From String.h and in libbe.so. + \sa BString::Compare(const BString &string) const */ /*! \fn int ICompare(const BString *, const BString *) +\brief Lexographically compare two strings in a case insensitive way. This function is useful if you need a global compare function to feed to BList::SortItems() for example. -\brief Lexographically compare two strings in a case insensitive way. +From String.h and in libbe.so. + \sa BString::Compare(const BString &string) const */ diff --git a/docs/user/support/support_archiving.dox b/docs/user/support/support_archiving.dox new file mode 100644 index 0000000000..fd94371e08 --- /dev/null +++ b/docs/user/support/support_archiving.dox @@ -0,0 +1,7 @@ +/*! +\page support_archiving Archiving and unarchiving objects. + +This document is also in the original BeBook, where it describes: +-# How to archive and unarchive an object +-# How to create an archivable object. +*/ \ No newline at end of file diff --git a/docs/user/support/support_intro.dox b/docs/user/support/support_intro.dox index 654da4d0c9..d3734c51f7 100644 --- a/docs/user/support/support_intro.dox +++ b/docs/user/support/support_intro.dox @@ -1,10 +1,11 @@ /*! -\ingroup support -\page supportintro The Support Kit +\page support_intro Introduction to the Support Kit The Support Kit provides a handy set of functions and classes that you can -use in your applications. +use in your applications. Have a look at the overview, or go straight to +the complete \link support list of components \endlink of this kit. +\section Overview
  • Threading utility classes:
      • @@ -14,12 +15,13 @@ use in your applications.
  • Archiving and IO:
      • -
    • BArchivable
      • +
    • BArchivable (\link support_archiving tutorial\endlink)
    • BFlattenable
    • BDataIO
      • BPositionIO
          • +
        • BBufferIO
        • BMemoryIO
        • BMallocIO
        @@ -32,8 +34,20 @@ use in your applications.
      • BString
    • BStopWatch
      • +
    • \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 + +For a better overview, have a look at \ref support_intro . +*/ +