diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 4d12059e3e..6d23915f4f 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -465,6 +465,8 @@ INPUT = . \ midi2 \ support \ ../../headers/os/drivers/fs_interface.h \ + ../../headers/os/drivers/USB3.h \ + ../../headers/os/drivers/USB_spec.h \ ../../headers/os/midi2 \ ../../headers/os/support \ ../../headers/posix/syslog.h diff --git a/docs/user/apidoc.dox b/docs/user/apidoc.dox index eac7dfe639..f333a562be 100644 --- a/docs/user/apidoc.dox +++ b/docs/user/apidoc.dox @@ -75,39 +75,37 @@ \subsection formalrequirements_headerblock The Header Block Every documentation file will begin with the header block. It's basically a - copyright block, with a reference to the author(s) and with the revision + copyright block, with a reference to the author(s) and with the revision against which the documentaton was written. \verbatim -// -// Copyright 2007, Haiku Inc. All Rights Reserved. -// -// Distributed under the terms of the MIT License. -// -// -// Documentation by: -// Niels Sascha Reedijk -// Corresponds to: -// /trunk/headers/os/support/String.h rev 19731 -// /trunk/src/kits/support/String.cpp rev 19731 -// +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/String.h rev 19731 + * /trunk/src/kits/support/String.cpp rev 19731 + * / \endverbatim The example above has a few elements that you should take note of: - -# First of all, every line starts with a C++ single line style comment. - So it starts with two slashes: \c //. If there is text on a line, the - tokens are followed by \e one space. If the text is part of a category, - such as Documentation by, put two spaces after the delimeter. + -# The header is put in a standard C comment, which are enclosed between + \c /* and \c *\/. + -# Every line starts with a whitespace and an asterix, followed by another + space. If the text is part of a category, such as Documentation + by, put three spaces after the delimeter. -# We start with a copyright notice. The first line is empty, then the - copyright notice, then another empty line, and then the line on \e MIT, - followed by two empty lines. + copyright notice, then the line on \e MIT, followed by an empty line. -# Then there is a label Documentation by:, which is followed by lines with names and email addresses between brackets. -# The final part is underneath the label Corresponds to:. Underneath there is a list of files and their svn revisions that the current documentation is known to correspond with. - -# The header block ends with an empty C++ comment, and the next block that - follows underneath will start after an empty line. + -# The header block ends with the \c *\/, where the asterix is alligned with + with the ones above it. \subsection formalrequirements_blocks Blocks diff --git a/docs/user/drivers/USB3.dox b/docs/user/drivers/USB3.dox new file mode 100644 index 0000000000..f19a7efac2 --- /dev/null +++ b/docs/user/drivers/USB3.dox @@ -0,0 +1,477 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/drivers/USB3.h rev 19915 + */ + +/*! + \file USB3.h + \ingroup drivers + \brief Interface for the USB module. +*/ + +/*! + \typedef struct usb_module_info usb_module_info + \brief The main interface object. See the usb_module_info documentation. +*/ + +/*! + \typedef uint32 usb_id + \brief Uniquely identify various USB objects that are used in the module. +*/ + +/*! + \typedef usb_id usb_device + \brief Uniquely identify USB devices. +*/ + +/*! + \typedef usb_id usb_interface + \brief Uniquely identify USB interfaces. +*/ + +/*! + \typedef usb_id usb_pipe + \brief Uniquely identify USB pipes. +*/ + +/*! + \typedef struct usb_endpoint_info usb_endpoint_info + \brief Container for USB endpoint descriptors. + \see Documentation for usb_endpoint_info. +*/ + +/*! + \typedef struct usb_interface_info usb_interface_info + \brief Container for USB interface descriptors. + \see Documentation for usb_interface_info. +*/ + +/*! + \typedef usb_interface_list usb_interface_list + \brief Container that holds a list of USB interface descriptors. + \see Documentation for usb_interface_list. +*/ + +/*! + \typedef struct usb_configuration_info usb_configuration_info + \brief Container for USB configuration descriptors. + \see Documentation for usb_configuration_info. +*/ + +///// usb_notify_hooks ///// + +/*! + \struct usb_notify_hooks + \brief Hooks that the USB stack can callback in case of events. +*/ + +/*! + \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie) + \brief Called by the stack in case a device is added. + + As soon as you have registered hooks using the + usb_module_info::install_notify() method, this hook will be called as soon as + a device is inserted that matches your provided usb_support_descriptor. + + \param device A unique id that identifies this USB device. + \param[in] cookie You can store a pointer to an object in this variable. + When the device is removed, this cookie will be provided to you. + \return You should return \c B_OK in case of success. If you return an error + value, the \a device id will become invalid and you will not be notified if + this device is removed. + \see device_removed() +*/ + +/*! + \var status_t (*usb_notify_hooks::device_removed)(void *cookie) + \brief Called by the stack in case a device you are using is removed. + + If you have accepted a device in the device_added() hook, this hook will + be called as soon as the device is removed. + + \param cookie The cookie you provided in the device_added() hook. Make sure + that you free the cookie, if necessary. + \return Currently the return value of this hook is ignored. It is recommended + to return \c B_OK though. +*/ + +///// usb_support_descriptor ///// + +/*! + \struct usb_support_descriptor + \brief Description of device descriptor that the driver can handle. + + Support descriptors can be used to match any form of class, subclass or + protocol, or a vendor and/or product. If any field has the value \c 0, it + is treated as a wildcard. + + For example, if you want to watch for all the hubs, which have a device + class of \c 0x09, you would pass this descriptor: + + \code + usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; + \endcode + + See usb_module_info::register_driver() for more information on how to use + this object. +*/ + +/*! + \var usb_support_descriptor::dev_class + \brief The supported device classes. +*/ + +/*! + \var usb_support_descriptor::dev_subclass + \brief The suported device subclasses. +*/ + +/*! + \var usb_support_descriptor::dev_protocol + \brief The supported device protocols. +*/ + +/*! + \var usb_support_descriptor::vendor + \brief The supported device vendor. +*/ + +/*! + \var usb_support_descriptor::product + \brief The supported device products. +*/ + +///// usb_endpoint_info ///// + +///// usb_interface_info ///// + +///// usb_interface_list ///// + +///// usb_configuration_info ///// + +///// usb_iso_packet_descriptor ///// + +///// usb_callback_func ///// + +/*! + \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength) + \brief Callback function for asynchronous transfers. + + \param cookie The cookie you supplied when you queued the transfer. + \param status The status of the transfer (whether it succeeded or not). + \param data The provided buffer. + \param actualLength The amount of bytes read or written during the transfer. +*/ + +///// usb_module_info ///// + +/*! + \struct usb_module_info + \brief Interface for drivers to interact with Haiku's USB stack. +*/ + +/*! + \var usb_module_info::binfo + \brief Instance of the bus_manager_info object. +*/ + +/*! + \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName) + \brief Register your driver. + + To let the USB stack know that a driver is available to support devices, a + driver needs to register itself first. To let the stack know which devices + it needs to notify the driver of, have a look at usb_support_descriptor. + + It is possible to supply a list of support constructors. You should allocate + an array of support constructors, and give the amount of constructors in the + array using the \a supportDescriptorCount parameter. + + In case your driver supports all devices, or more likely, in case you want to + monitor all devices plugged in and removed, it is safe to pass \c NULL to the + \a supportDescriptors paramater and zero (0) to \a supportDescriptorCount. + + \param driverName A unique name that identifies your driver. Avoid names like + \c webcam or \c mouse, instead use vendor names and device types to avoid + nameclashes. The install_notify() and uninstall_notify() functions use the + driver name as an identifier. + \param supportDescriptors An array of the type usb_support_descriptor. Pass + the amount of objects in the next parameter. + \param supportDescriptorCount The number of objects in the array supplied in + the previous parameter. + \param optionalRepublishDriverName Undocumented parameter. It is safe to + pass \c NULL. + \retval B_OK The driver is registered. You can now call install_notify() + \retval B_BAD_VALUE You passed \c NULL as \a driverName. + \retval B_ERROR General internal error in the USB stack. You may retry the + request in this case. + \retval B_NO_MEMORY Error allocating some internal objects. The system is + out of memory. +*/ + +/*! + \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks) + \brief Install notify hooks for your driver. + + After your driver is registered, you need to pass hooks to your driver that + are called whenever a device that matches your \link usb_support_descriptor + support descriptor \endlink . + + As soon as the hooks are installed you'll receive callbacks for devices that + are already attached, so make sure your driver is initialized properly when + calling this method. + + \param driverName The name you passed in register_driver(). + \param hooks The hooks the stack should call in case the status of devices + that match your support descriptor changes. + \retval B_OK Hooks are installed succesfully. + \retval B_NAME_NOT_FOUND Invalid \a driverName. + + \see usb_notify_hooks for information on how your hooks should behave. + \see uninstall_notify() +*/ + +/*! + \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName) + \brief Uninstall notify hooks for your driver. + + If your driver needs to stop, you can uninstall the notifier hooks. This will + clear the stored hooks in the driver and you will not receive any + notifications when new devices are attached. This method will also call + usb_notify_hooks::device_removed() for all the devices that you are using and + all the stack's resources that are allocated to your driver are cleared. + + \param driverName The name you passed in register_driver(). + \retval B_OK Hooks are uninstalled. + \retval B_NAME_NOT_FOUND Invalid \a driverName. +*/ + +/*! + \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device) + \brief Get the device descriptor. + + \param device The id of the device you want to query. + \return The standard usb_device_descriptor, or \c NULL in case of an error. +*/ + +/*! + \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index) + \brief Get a configuration descriptor by index. + + \param device The id of the device you want to query. + \param index The (zero based) offset of the list of configurations. + \return The usb_configuration_info with the standard usb configuration + descriptor, or \c NULL if the \a id is invalid or the \a index is out of + bounds. +*/ + +/*! + \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device) + \brief Get the current configuration. + + \param id The id of the device you want to query. + \retval The usb_configuration_info with the standard usb configuration + descriptor, or \c NULL if the \a id is invalid. +*/ + +/*! + \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration) + \brief Change the current configuration. + + Changing the configuration will destroy all the current endpoints. If the + \a configuration points to the current configuration, the request will be + ignored and \c B_OK will be returned. + + \param device The id of the device you want to query. + \param configuration The pointer to the new configuration you want to set. + \retval B_OK The new configuration is set succesfully. + \retval B_DEV_INVALID_PIPE The \a device parameter is invalid. + \retval B_BAD_VALUE The configuration does not exist. + + \note This method also allows you to completely unconfigure the device, which + means that all the current endpoints, pipes and transfers will be freed. + Pass \c NULL to the parameter \a configuration if you want to do that. +*/ + +/*! + \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface) + \brief Set an alternative interface. Not implemented. + + This method currently always returns \c B_ERROR. +*/ + +/*! + \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe set feature requests. + + Both the set_feature() and clear_feature() requests work on all the Stack's + objects: devices, interfaces and pipes. + + \param handle The object you want to query. + \param selector The value you want to pass in the feature request. + \return \c B_OK in case the request succeeded and the device responded + positively, or an error code in case it failed. +*/ + +/*! + \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe clear feature requests. + + \see set_feature() to see how this method works. +*/ + +/*! + \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status) + \brief Convenience function for standard usb status requests. + + \param[in] handle The object you want to query. + \param[out] status A variable in which the device can store it's status. + \return \c B_OK in case the request succeeded and the device responded + positively, or an error code in case it failed. +*/ + +/*! + \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength, size_t *actualLength) + \brief Convenience function to get a descriptor from a device. + + \param[in] device The device you want to query. + \param[in] descriptorType The type of descriptor you are requesting. + \param[in] index In case there are multiple descriptors of this type, you + select which one you want. + \param[in] languageID The language you want the descriptor in (if applicable, + like with string_descriptors). + \param[out] data The buffer in which the descriptor can be written. + \param[in] dataLength The size of the buffer (in bytes). + \param[out] actualLength A pointer to a variable in which the actual number + of bytes written can be stored. + \retval B_OK The request succeeded, and the descriptor is written. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. +*/ + +/*! + \fn status_t (*usb_module_info::send_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, size_t *actualLength) + \brief Send a generic, synchronous request over the default control pipe. + + See queue_request() for an asynchronous version of this method. + + Most of the standard values of a request are defined in USB_spec.h. + + \param[in] device The device you want to query. + \param[in] requestType The request type. + \param[in] request The request you want to perform. + \param[in] value The value of the request. + \param[in] index The index for the request. + \param[in] length The size of the buffer pointed by \a data + \param[out] data The buffer where to put the result in. + \param[out] actualLength The actual numbers of bytes written. + + \retval B_OK The request succeeded. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. +*/ + +/*! + \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue an interrupt transfer. + + \param pipe The id of the pipe you want to query. + \param data The data buffer you want to pass. + \param dataLength The size of the data buffer. + \param callback The callback function the stack should call after finishing. + \param callbackCookie A cookie that will be supplied to your callback + function when the transfer is finished. + + \return Whether or not the queueing of the transfer went well. The return + value won't tell you if the transfer actually succeeded. + \retval B_OK The interrupt transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a pipe is invalid. +*/ + +/*! + \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk transfer. + + This method behaves like the queue_interrupt() method, except that it queues + a bulk transfer. +*/ + +/*! + \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk vector. + + This method behaves like the queue_interrupt() method, except that it queues + bulk transfers and that it is based on an (array of) io vectors. + + \param vector One or more io vectors. IO vectors are standard POSIX entities. + \param vectorCount The number of elements in the \a vector array. +*/ + +/*! + \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a isochronous transfer. Not implemented. + + Not implemented in the current Haiku USB Stack. +*/ + +/*! + \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a control pipe request. + + This method does roughly the same as send_request(), however, it works + asynchronously. This means that the method will return as soon as the + transfer is queued. + + \param callback The callback function for when the transfer is done. + \param callbackCookie The cookie that the stack should pass to your callback + function. + \return Whether or not the queueing of the transfer went well. The return + value won't tell you if the transfer actually succeeded. + \retval B_OK The control transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a callback is invalid. +*/ + +/*! + \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize) + \brief Set some pipe features. + + The USB standard specifies some properties that should be able to be set on + isochronous pipes. If your driver requires the properties to be changed, you + should use this method. + + \param pipe The id of the isochronous pipe you want to alter. + \param maxNumQueuedPackets The maximum number of queued packets allowed on + this pipe. + \param maxBufferDurationMS The maximum time in ms that the buffers are valid. + \param sampleSize The size of the samples through this pipe. + \retval B_OK Pipe policy changed. + \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an + isochronous pipe. +*/ + +/*! + \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe) + \brief Cancel pending transfers. Not Implemented. + + Call this method to cancel pending transfers in a \a pipe. + + \warning This is currently not implemented! + + \param pipe The id of the pipe to clear. The method will always return + \c B_ERROR. +*/ + +/*! + \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize) + \brief Low level commands to the USB stack. + + This method is used to give lowlevel commands to the Stack. There are + currently no uses documented. +*/ diff --git a/docs/user/drivers/USB_spec.dox b/docs/user/drivers/USB_spec.dox new file mode 100644 index 0000000000..954749a21c --- /dev/null +++ b/docs/user/drivers/USB_spec.dox @@ -0,0 +1,296 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/drivers/USB_spec.h rev 19915 + */ + +/*! + \file USB_spec.h + \brief General definitions as defined by the USB standard. +*/ + +/*! + \name Request Types: targets and direction + + These request types can be used in the usb_module_info::send_request() + and usb_module_info::queue_request() methods. They specifiy both the type + of interface and the direction of the transfer. + + These are usually combined with a category (found on this page). +*/ + +//! @{ + +/*! + \def USB_REQTYPE_DEVICE_IN + \brief Device. In. +*/ + +/*! + \def USB_REQTYPE_DEVICE_OUT + \brief Device. Out. +*/ + +/*! + \def USB_REQTYPE_INTERFACE_IN + \brief Interface. In. +*/ + +/*! + \def USB_REQTYPE_INTERFACE_OUT + \brief Interface. Out. +*/ + +/*! + \def USB_REQTYPE_ENDPOINT_IN + \brief Endpoint. In. +*/ + +/*! + \def USB_REQTYPE_ENDPOINT_OUT + \brief Endpoint. Out. +*/ + +/*! + \def USB_REQTYPE_OTHER_OUT + \brief Other. Out. +*/ + +/*! + \def USB_REQTYPE_OTHER_IN + \brief Other. In. +*/ + +//! @} + +/*! + \name Request Types: categories + + These request types can be used in the usb_module_info::send_request() + and usb_module_info::queue_request() methods. They specifiy the category + of the transfer. + + These are usually combined with a target and direction (found on this page). +*/ + +//! @{ + +/*! + \def USB_REQTYPE_STANDARD + \brief Request that adheres to the USB specifications. +*/ + +/*! + \def USB_REQTYPE_CLASS + \brief Request that adheres to the specifications of the class. +*/ + +/*! + \def USB_REQTYPE_VENDOR + \brief Request that is defined by the specifications of the vendor. +*/ + +/*! + \def USB_REQTYPE_RESERVED + \brief Reserved for special implementations. +*/ + +/*! + \def USB_REQTYPE_MASK + \brief Constant that can be used as mask over the requesttype field. +*/ + +//! @} + +/*! + \name Standard Request Values + + These request values are defined by the USB standard. You can use these + constants in both the usb_module_info::send_request() and + usb_module_info::queue_request() methods. + + \warning The stack handles most of these standard requests for you. Use the + supplied convenience functions the the usb_module_info interface rather than + doing the requests yourself. Some of these request may actually interfere + with the inner workings of the USB stack! +*/ + +//! @{ + +/*! + \def USB_REQUEST_GET_STATUS + \brief Get the status of a device. +*/ + +/*! + \def USB_REQUEST_CLEAR_FEATURE + \brief Clear a feature. +*/ + +/*! + \def USB_REQUEST_SET_FEATURE + \brief Set a feature. +*/ + +/*! + \def USB_REQUEST_SET_ADDRESS + \brief Set the device address. +*/ + +/*! + \def USB_REQUEST_GET_DESCRIPTOR + \brief Get a descriptor. +*/ + +/*! + \def USB_REQUEST_SET_DESCRIPTOR + \brief Update a descriptor to a supplied one. +*/ + +/*! + \def USB_REQUEST_GET_CONFIGURATION + \brief Get a configuration. +*/ + +/*! + \def USB_REQUEST_SET_CONFIGURATION + \brief Set the configuration. +*/ + +/*! + \def USB_REQUEST_GET_INTERFACE + \brief Request an interface descriptor. +*/ + +/*! + \def USB_REQUEST_SET_INTERFACE + \brief Set a specific interface. +*/ + +/*! + \def USB_REQUEST_SYNCH_FRAME + \brief Synchronize a frame. +*/ + +//! @} + +/*! + \name Descriptor Constants + + These constants refer to a specific descriptor. They can be used when + building a standard USB request for a descriptor, or in the + usb_module_info::get_descriptor() method. +*/ + +//! @{ + +/*! + \def USB_DESCRIPTOR_DEVICE + \brief Constant for the device descriptor. +*/ + +/*! + \def USB_DESCRIPTOR_CONFIGURATION + \brief Constant for a configuration descriptor. +*/ + +/*! + \def USB_DESCRIPTOR_STRING + \brief Constant for a string descriptor. +*/ + +/*! + \def USB_DESCRIPTOR_INTERFACE + \brief Constant for an interface descriptor. +*/ + +/*! + \def USB_DESCRIPTOR_ENDPOINT + \brief Constant for an endpoint descriptor. +*/ + +//! @} + +/*! + \name Feature Requests + + These constants refer to standard feature requests. You can use these using + the convenient usb_module_info::set_feature() and + usb_module_info::clear_feature() methods. +*/ + +//! @{ + +/*! + \def USB_FEATURE_DEVICE_REMOTE_WAKEUP + \brief Request a device to wakeup from remote calls. +*/ + +/*! + \def USB_FEATURE_ENDPOINT_HALT + \brief Request for a specific endpoint to halt. +*/ + +//! @} + +/*! + \name Endpoint Attributes + + These constants refer to values in the usb_endpoint_descriptor::attributes + field. +*/ + +//! @{ + +/*! + \def USB_ENDPOINT_ATTR_CONTROL + \brief Endpoint facilitates control transfers. +*/ + +/*! + \def USB_ENDPOINT_ATTR_ISOCHRONOUS + \brief Endpoint facilitates isochronous transfers. +*/ + +/*! + \def USB_ENDPOINT_ATTR_BULK + \brief Endpoint facilitates bulk transfers. +*/ + +/*! + \def USB_ENDPOINT_ATTR_INTERRUPT + \brief Endpoint facilitates interrupt transfers. +*/ + +/*! + \def USB_ENDPOINT_ATTR_MASK + \brief Constant to mask out transfer types. +*/ + +//! @} + +/*! + \name Endpoint Address + + These constants refer to the direction that is embedded in the + usb_endpoint_descriptor::address field. +*/ + +//! @{ + +/*! + \def USB_ENDPOINT_ADDR_DIR_IN + \brief The endpoint provides data for the driver. +*/ + +/*! + \def USB_ENDPOINT_ADDR_DIR_OUT + \brief The endpoint accepts data from the host. +*/ + +//! @} + diff --git a/docs/user/drivers/drivers.dox b/docs/user/drivers/drivers.dox index a7eee02e01..edd6ae043f 100644 --- a/docs/user/drivers/drivers.dox +++ b/docs/user/drivers/drivers.dox @@ -4,5 +4,6 @@ \section topics Topics - \ref fs_modules +- \ref usb_modules */ diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox index 3958e03029..62acc939df 100644 --- a/docs/user/drivers/fs_interface.dox +++ b/docs/user/drivers/fs_interface.dox @@ -325,7 +325,7 @@ with the user's access permissions, the function shall return \c B_OK. For most FSs the permissions a user has are defined by the \c st_mode, \c st_uid, and \c st_gid fields of the node's stat data. As a special -exception, the root user (geteuid() == 0<\tt>) does always have +exception, the root user (geteuid() == 0) does always have read and write permissions, execution permission only when at least one of the execution permission bits are set. diff --git a/docs/user/drivers/usb_modules.dox b/docs/user/drivers/usb_modules.dox new file mode 100644 index 0000000000..4691cf4ea6 --- /dev/null +++ b/docs/user/drivers/usb_modules.dox @@ -0,0 +1,18 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + */ + +/*! + \page usb_modules Writing drivers for USB devices + + This page will describe how the Haiku USB stack is structured. +*/ + + + + + \ No newline at end of file diff --git a/docs/user/midi2/midi2intro.dox b/docs/user/midi2/midi2intro.dox index 4243e955ab..53dbdb7e12 100644 --- a/docs/user/midi2/midi2intro.dox +++ b/docs/user/midi2/midi2intro.dox @@ -287,12 +287,12 @@ More about the Midi Kit: - \ref Midi2Defs.h - Be Newsletter Volume 3, Issue 47 - Motor Mix sample code - Be Newsletter Volume 4, Issue 3 - Overview of the new kit -- OpenBeOS - Newsletter 33, Introduction to MIDI, Part 1 -- OpenBeOS - Newsletter 36, Introduction to MIDI, Part 2 +- Newsletter + 33, Introduction to MIDI, Part 1 +- Newsletter + 36, Introduction to MIDI, Part 2 - Sample code and other goodies at the - OpenBeOS Midi Kit team page + Haiku Midi Kit team page Information about MIDI in general: diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox new file mode 100644 index 0000000000..89a99bddfe --- /dev/null +++ b/docs/user/support/Archivable.dox @@ -0,0 +1,172 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/Archivable.h rev 19972 + * /trunk/src/kits/support/Archivable.cpp rev 19095 + */ + +/*! + \file Archivable.h + \brief Provides the BArchivable interface. +*/ + +/*! + \class BArchivable + \ingroup support + \ingroup libbe + \brief Interfaced for objects that can be archived into a BMessage. + + BArchivable provides an interface for objects that can be archived into + messages and unarchived to objects in another location. By these means you + are able to send objects between applications, or even between computers over + networks. + + BArchivable differs from BFlattenable in way that BFlattenable is designed to + store objects to flat streams of data, where the main objective is storing it + to disk. The objective of this interface is to archive objects that will be + restored as objects. To illustrate that point, BArchivable messages know how + to restore itself, whereas BFlattenables have a datatype which you manually + need to map to classes. + + Archiving is done with the Archive() method. If your class support it, the + caller can request your class to to a deep archivation, which means that all + child objects should be stored. Unarchiving works with the Instantiate() + method, which is static. However, since the interface is designed to + unarchive objects without the caller knowing what kind of object it + actually is, the global function #instantiate_object() instantiates a message + without you manually having to determine the class the message is from. This + adds considerable flexibility and allows BArchivable to be used in + combination with add-ons. + + To provide this interface in your classes, you should publicly inherit this + class. You should reimplement Archive() and Instantiate(), and provide one + constructor that takes one BMessage argument. +*/ + +/*! + \fn BArchivable::BArchivable(BMessage* from) + \brief Constructor. Does nothing. + + If you inherit this interface, you should at least provide one constructor + that takes one BMessage argument. +*/ + +/*! + \fn BArchivable::BArchivable() + \brief Constructor. Does nothing. +*/ + +/*! + \fn BArchivable::~BArchivable() + \brief Destructor. Does nothing. +*/ + +/*! + \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const + \brief Archive the object into a BMessage. + + You should call this method from your derived implementation, as it finishes + the message to contain data to instantiate your object. + + \param into The message you may store your object in. + \param deep If \c true, all child object of this object should be stored as + well. Naturally, only pay attention of this parameter if you actually have + child objects. + \retval B_OK The archiving succeeded. + \retval "error codes" The archiving did not succeed. +*/ + +/*! + \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) + \brief Static member to restore objects from messages. + + You should always check that the \a archive argument actually corresponds to + your class. The automatic functions, such as #instantiate_object() will not + choose the wrong class, but some manual calls to this member might be faulty. + + \param archive The message with the data to restore an object. + \retval You should return a pointer to your object, or \c NULL if you + failed to succeed. + \warning The default implementation will always return \c NULL. Even though + it is possible to store plain BArchive objects, it is impossible to restore + them. + \see instantiate_object(BMessage *from) +*/ + +/*! + \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) + \brief Internal method. + \internal This method is used to extend the API or to provide 'hidden' + features. Currently nothing of interest is implemented. +*/ + +///////////////////// Global methods +/*! + \addtogroup support_globals + @{ +*/ + +/*! + \typedef typedef BArchivable* (*instantiation_func)(BMessage*) + \brief Internal definition of a function that can instantiate objects that + have been created with the BArchivable API. +*/ + +/*! + \fn BArchivable* instantiate_object(BMessage *from, image_id *id) + \brief Instantiate an archived object with the object being defined in a + different application or library. + + This function is similar to instantiate_object(BMessage *from), except that + it takes the \a id argument that refers to an image where the object might + come from. + + \note Images are names for executable files. Image ids refer to these + executable files that have been loaded by your application. Have a look + at the kernel API. +*/ + +/*! + \fn BArchivable* instantiate_object(BMessage *from) + \brief Instantiate an archived object. + + This global function will determine the base class based on the \a from + argument, and it will call the Instantiate() function of that object to + restore it. + + \param from The archived object. + \return The object returns a pointer to the instantiated object, or \c NULL + if the instantiation failed. The global \c errno variable will contain the + reason it failed. + \see instantiate_object(BMessage *from, image_id *id) +*/ + +/*! + \fn bool validate_instantiation(BMessage* from, const char* className) + \brief Internal function that checks if the \a className is the same as the + one stored in the \a from message. +*/ + +/*! + \fn instantiation_func find_instantiation_func(const char* className, const char* signature) + \brief Internal function that searches for the instantiation func with a + specific signature. Use instantiate_object() instead. +*/ + +/*! + \fn instantiation_func find_instantiation_func(const char* className) + \brief Internal function that searches for the instantiation func of a + specific class. Use instantiate_object() instead. +*/ + +/*! + \fn instantiation_func find_instantiation_func(BMessage* archive) + \brief Internal function that searches for the instantiation func that + works on the specified \a archive. Use instantiate_object() instead. +*/ + +//! @} diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox index 31e45b5192..6b0c6f5b9f 100644 --- a/docs/user/support/Autolock.dox +++ b/docs/user/support/Autolock.dox @@ -1,26 +1,36 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/Autolock.h rev 19972 + */ + /*! -\file Autolock.h -\brief Implements a handy locking utility. + \file Autolock.h + \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 @@ -43,7 +53,8 @@ Receiver::HandleCall(Call *call) } \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) @@ -61,43 +72,43 @@ Receiver::HandleCall(Call *call) } \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. */ diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox index 15cf1929b4..a33895133a 100644 --- a/docs/user/support/Beep.dox +++ b/docs/user/support/Beep.dox @@ -1,32 +1,57 @@ -/*! -\file Beep.h -\brief Functions to generate sounds from the computer. +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/Beep.h rev 19972 + * /trunk/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. */ /*! -\addtogroup support_globals -@{ + \addtogroup support_globals +*/ + +//! @{ + +/*! + \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 beep() -\brief TODO: Not implemented nor documented. + \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. + From Beep.h and in libbe.so. */ /*! -\fn status_t system_beep(const char* eventName) -\brief TODO: Not implemented nor documented. + \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. -*/ - -/*! -\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. + From Beep.h and in libbe.so. + + \param eventName The name of the event. + \param flags Currently unused. Pass \c 0. */ //! @} \ No newline at end of file diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox index 13561aa61a..f942635bd1 100644 --- a/docs/user/support/BlockCache.dox +++ b/docs/user/support/BlockCache.dox @@ -1,108 +1,121 @@ -/*! -\file BlockCache.h -\brief Implements a mechanism to store and retrieve memory blocks +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/BlockCache.h rev 19972 + * /trunk/src/kits/support/BlockCache.cpp rev 4568 + */ + + /*! + \file BlockCache.h + \brief Implements a mechanism to store and retrieve memory blocks */ /*! -\var B_OBJECT_CACHE -\brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c new[] and \c delete[]. + \var B_OBJECT_CACHE + \brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c new[] and \c delete[]. */ /*! -\var B_MALLOC_CACHE -\brief Used in the constructor of BBlockCache. Determines that objects will - be created using \c malloc() and \c free(). + \var B_MALLOC_CACHE + \brief Used in the constructor of BBlockCache. Determines that objects will + be created using \c malloc() and \c free(). */ /*! -\class BBlockCache -\ingroup support -\ingroup libbe -\brief A class that creates and maintains a pool of memory blocks. + \class BBlockCache + \ingroup support + \ingroup libbe + \brief A class that creates and maintains a pool of memory blocks. -In some performance critical code there might come a time where you -require a lot of little blocks of memory that you want to access and -dispose of continuously. Since allocating and freeing memory are an -'expensive' operation, it's better to have a pool of memory blocks at -your disposal. Luckily, the Haiku API provides a class that will act -as the administrator of your memory pool, so you won't have to reinvent -the wheel. + In some performance critical code there might come a time where you + require a lot of little blocks of memory that you want to access and + dispose of continuously. Since allocating and freeing memory are an + 'expensive' operation, it's better to have a pool of memory blocks at + your disposal. Luckily, the Haiku API provides a class that will act + as the administrator of your memory pool, so you won't have to reinvent + the wheel. -The principle is easy. The constructor takes the number of blocks you -want to create beforehand, the size of the blocks and the method of -allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE. -The first uses C++ operators \c new[] and \c delete[], the second uses -\c malloc() and \c free(). Unless you have specific demands on performance -or you want to take care of freeing the objects yourself, either use is fine. + The principle is easy. The constructor takes the number of blocks you + want to create beforehand, the size of the blocks and the method of + allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE. + The first uses C++ operators \c new[] and \c delete[], the second uses + \c malloc() and \c free(). Unless you have specific demands on performance + or you want to take care of freeing the objects yourself, either use is fine. -As soon as you have the memory pool, you can Get() blocks. If the -pre-allocated memory blocks run out, BBlockCache will allocate -new ones, so you won't have to worry about availability. As soon as -you're done, you can Save() the memory back into the pool, though -BBlockCache will make sure that there won't be more blocks saved -than the initial number you said when you created the object. + As soon as you have the memory pool, you can Get() blocks. If the + pre-allocated memory blocks run out, BBlockCache will allocate + new ones, so you won't have to worry about availability. As soon as + you're done, you can Save() the memory back into the pool, though + BBlockCache will make sure that there won't be more blocks saved + than the initial number you said when you created the object. -As soon as you got a pointer from the Get() method, you own that -block of memory. This means that you have the liberty to dispose -of it yourself. It also means that when you delete your BBlockCache -instance, any blocks of memory that are checked out won't be destroyed. -In case you might want to delete your objects yourself, make sure you -use the proper way. If you created the object as #B_OBJECT_CACHE -use \c delete[] to free your object. If you created the object -as #B_MALLOC_CACHE, use \c free(). Please note that it defeats -the purpose of this class if your are going to free all the objects yourself, -since it basically means that when the pool runs out, Get() will be allocating -the objects itself. + As soon as you got a pointer from the Get() method, you own that + block of memory. This means that you have the liberty to dispose + of it yourself. It also means that when you delete your BBlockCache + instance, any blocks of memory that are checked out won't be destroyed. + In case you might want to delete your objects yourself, make sure you + use the proper way. If you created the object as #B_OBJECT_CACHE + use \c delete[] to free your object. If you created the object + as #B_MALLOC_CACHE, use \c free(). Please note that it defeats + the purpose of this class if your are going to free all the objects yourself, + since it basically means that when the pool runs out, Get() will be allocating + the objects itself. -\note BBlockCache is thread-safe. + \note BBlockCache is thread-safe. */ /*! -\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType) -\brief Allocate a new memory pool. + \fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32 allocationType) + \brief Allocate a new memory pool. -\param blockCount The number of free memory blocks you want to initially allocate. - This number is also used as a maximum number of free blocks that will be kept. -\param blockSize The size of the blocks. -\param allocationType Either #B_OBJECT_CACHE for using \c new[] and \c delete[] - or #B_MALLOC_CACHE for \c malloc() and \c free(). + \param blockCount The number of free memory blocks you want to initially + allocate. This number is also used as a maximum number of free blocks that + will be kept. + \param blockSize The size of the blocks. + \param allocationType Either #B_OBJECT_CACHE for using \c new[] and + \c delete[] or #B_MALLOC_CACHE for \c malloc() and \c free(). */ /*! -\fn BBlockCache::~BBlockCache() -\brief Destroy the empty blocks in the free list. + \fn BBlockCache::~BBlockCache() + \brief Destroy the empty blocks in the free list. -Note that the blocks you checked out with Get() and not checked back in with -Save() will not be freed, since ownership belongs to you. Make sure you clean up -after yourself. + Note that the blocks you checked out with Get() and not checked back in with + Save() will not be freed, since ownership belongs to you. Make sure you clean + up after yourself. */ /*! -\fn void *BBlockCache::Get(size_t blockSize) -\brief Get a block from the pool of free blocks. + \fn void *BBlockCache::Get(size_t blockSize) + \brief Get a block from the pool of free blocks. -If the pool runs out of free blocks, a new one will be allocated. Please note that -if the size given in the \c blockSize parameter is different from the size given -in the constructor, that a new block of memory will be created. Only sizes that -match the blocks in the memory pool will come from the pool. + If the pool runs out of free blocks, a new one will be allocated. Please note + that if the size given in the \c blockSize parameter is different from the + size given in the constructor, that a new block of memory will be created. + Only sizes that match the blocks in the memory pool will come from the pool. -\param blockSize The required size of the memory block. -\return Returns a pointer to a memory block, or \c NULL if locking the object -failed. + \param blockSize The required size of the memory block. + \return Returns a pointer to a memory block, or \c NULL if locking the object + failed. */ /*! -\fn void BBlockCache::Save(void *pointer, size_t blockSize) -\brief Save a block of memory to the memory pool. + \fn void BBlockCache::Save(void *pointer, size_t blockSize) + \brief Save a block of memory to the memory pool. -The block of memory will only be added to the pool if the \c blockSize is equal -to the size the object was created with, and if the maximum number free blocks -in the list won't be passed. Else the memory will be freeed. + The block of memory will only be added to the pool if the \c blockSize is + equal to the size the object was created with, and if the maximum number + free blocks in the list won't be passed. Else the memory will be freeed. -Note that it is perfectly valid to pass objects other than you got from Get(), but -please note that the way it was created confirms with the way memory is allocated -and freed in this pool. Thus, only feed blocks that were created with \c new[] if -the allocation type is #B_OBJECT_CACHE, likewise use only objects allocated -with \c malloc() when the allocation type is #B_MALLOC_CACHE. + Note that it is perfectly valid to pass objects other than you got from + Get(), but please note that the way it was created confirms with the way + memory is allocated and freed in this pool. Thus, only feed blocks that were + created with \c new[] if the allocation type is #B_OBJECT_CACHE, likewise + use only objects allocated with \c malloc() when the allocation type is + #B_MALLOC_CACHE. */ diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index db42fe8e13..571c5b72c2 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -1,15 +1,13 @@ -// -// Copyright 2007, Haiku Inc. All Rights Reserved. -// -// Distributed under the terms of the MIT License. -// -// -// Documentation by: -// Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/List.h rev 19972 + * /trunk/src/kits/support/List.cpp rev 18649 + */ /*! \file List.h diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox index 06905af9a5..060bd67dac 100644 --- a/docs/user/support/SupportDefs.dox +++ b/docs/user/support/SupportDefs.dox @@ -1,3 +1,13 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/SupportDefs.h rev 19972 + */ + /*! \file SupportDefs.h \ingroup support diff --git a/docs/user/support/parsedate.dox b/docs/user/support/parsedate.dox index 44a501bba8..a78b230908 100644 --- a/docs/user/support/parsedate.dox +++ b/docs/user/support/parsedate.dox @@ -1,170 +1,188 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Axel Dörfler + * Corresponds to: + * /trunk/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). - -\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. + 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. */ -/** \def PARSEDATE_RELATIVE_TIME -\brief relative time +/*! + \def PARSEDATE_RELATIVE_TIME + \brief relative time -The time value was computed relative to the specified time. + The time value was computed relative to the specified time. */ -/** \def PARSEDATE_DAY_RELATIVE_TIME -\brief day relative 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. + 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 +/*! + \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. + 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 +/*! + \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. + 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 dateString relative to relativeTo +/*! + \fn time_t parsedate(const char *dateString, time_t relativeTo) + \brief Parses \a dateString relative to \a relativeTo -Parses the given dateString relative to the time -specified by 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 is passed, the current time will be used -\return the parsed time value or -1 if the dateString -could not be parsed. + \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 + could not be parsed. */ -/** \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) -\brief Parses dateString relative to relativeTo +/*! + \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) + \brief Parses dateString relative to relativeTo -This does basically the same as parsedate(), but will set the following -flags in _storedFlags: -\htmlonly - - - - - - - - - - - -
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly -
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly -
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly -
PARSEDATE_INVALID_DATE - \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly - This flag will only be set if the function returns -1. -
-\endhtmlonly + This does basically the same as parsedate(), but will set the following + flags in _storedFlags: + \htmlonly + + + + + + + + + + + +
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly +
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly +
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly +
PARSEDATE_INVALID_DATE + \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly + This flag will only be set if the function returns -1. +
+ \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 formatTable 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! +/*! + \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 formatTable 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! */ -/** \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() */ diff --git a/docs/user/support/stopwatch.dox b/docs/user/support/stopwatch.dox index bfaa5e9492..d7e9e1ee64 100644 --- a/docs/user/support/stopwatch.dox +++ b/docs/user/support/stopwatch.dox @@ -1,82 +1,100 @@ -/*! -\file StopWatch.h -\brief Provides the BStopWatch class. +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation written by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/StopWatch.h rev 19972 + * /trunk/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. + \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. + 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(const char *name, bool silent) -\brief Constructs a BStopWatch object and starts the timer. + \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 -silentparameter. Whenever the object is destroyed, information on -the elapsed time will be streamed to standard output. + 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. + \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. */ /*! -\fn BStopWatch::~BStopWatch() -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() + \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::Resume() -\brief Resumes the timer when it is in a suspended state. -\sa Suspend() + \fn void BStopWatch::Resume() + \brief Resume the timer when it is in a suspended state. + \see Suspend() */ /*! -\fn void BStopWatch::Suspend() -\brief Suspend the timer. -\sa Resume() + \fn void BStopWatch::Suspend() + \brief Suspend the timer. + \see Resume() */ /*! -\fn bigtime_t BStopWatch::Lap() -\brief Start a new lap. + \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. + 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. + \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 bigtime_t BStopWatch::ElapsedTime() const -\brief Get the elapsed time the object has counted. -\return The elapsed time in microseconds. + \fn bigtime_t BStopWatch::ElapsedTime() const + \brief Get the elapsed time the object has counted. + \return The elapsed time in microseconds. */ /*! -\fn void BStopWatch::Reset() -\brief Restart the timer + \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. + 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. + \fn const char *BStopWatch::Name() const + \brief Get the name. + \return the name given to the object at creation time. */ \ No newline at end of file diff --git a/docs/user/support/string.dox b/docs/user/support/string.dox index 4a08436d6f..edb694ad80 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/string.dox @@ -1,15 +1,13 @@ -// -// Copyright 2007, Haiku Inc. All Rights Reserved. -// -// Distributed under the terms of the MIT License. -// -// -// Documentation by: -// Niels Sascha Reedijk -// Corresponds to: -// /trunk/headers/os/support/String.h rev 19731 -// /trunk/src/kits/support/String.cpp rev 19731 -// +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/String.h rev 19731 + * /trunk/src/kits/support/String.cpp rev 19731 + */ /*! \file String.h diff --git a/docs/user/support/support_archiving.dox b/docs/user/support/support_archiving.dox deleted file mode 100644 index fd94371e08..0000000000 --- a/docs/user/support/support_archiving.dox +++ /dev/null @@ -1,7 +0,0 @@ -/*! -\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 e06063611f..2335a018f9 100644 --- a/docs/user/support/support_intro.dox +++ b/docs/user/support/support_intro.dox @@ -1,3 +1,11 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + */ + /*! \page support_intro Introduction to the Support Kit @@ -11,7 +19,7 @@ - BAutolock - Thread Local Storage - Archiving and IO: - - BArchivable (\link support_archiving tutorial\endlink) + - BArchivable - BFlattenable - BDataIO - BPositionIO @@ -34,8 +42,8 @@ // 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 . */ diff --git a/docs/user/support/syslog.dox b/docs/user/support/syslog.dox index 44a4ff4b94..82cc2133e0 100644 --- a/docs/user/support/syslog.dox +++ b/docs/user/support/syslog.dox @@ -1,228 +1,293 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation written by: + * Axel Dörfler + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/posix/syslog.h rev 6684 + */ + /*! -\file syslog.h -\ingroup support -\ingroup libroot -\brief System logging capabilities + \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. + 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 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 +/*! + \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. + 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 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 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 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 +/*! + \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. + 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 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 int setlogmask_team(int priorityMask) + \brief sets the logging priority mask */ -/*! \fn void closelog_thread(void) -\brief Closes the log +/*! + \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 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 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 +/*! + \fn int setlogmask_thread(int priorityMask) + \brief sets the logging priority mask */ -/*! @{ -\name Options for openlog() +/*! + \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() */ -/*! \def LOG_KERN -\brief Reserved for messages generated by the kernel. +//! @{ + +/*! + \def LOG_KERN + \brief Reserved for messages generated by the kernel. */ -/*! \def LOG_USER -\brief Reserved for messages generated by user processes. +/*! + \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_MAIL + \brief Standard (?) POSIX facility for messages by the mailing daemon. */ -/*! \def LOG_DAEMON -\brief Standard POSIX (?) facility for messages by daemons (and Haiku servers). +/*! + \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_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_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_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_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_UUCP + \brief Reserved for messages generated by UUCP */ -/*! \def LOG_CRON -\brief Reserved for messages generated by the CRON daemon. +/*! + \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_AUTHPRIV + \brief Reserved for private (?) messages that relate to authentication. */ -/*! \def LOG_LOCAL0 -\brief Use this for local use. +/*! + \def LOG_LOCAL0 + \brief Use this for local use. */ -/*! \def LOG_LOCAL1 -\brief Use this for local use. +/*! + \def LOG_LOCAL1 + \brief Use this for local use. */ -/*! \def LOG_LOCAL2 -\brief Use this for local use. +/*! + \def LOG_LOCAL2 + \brief Use this for local use. */ -/*! \def LOG_LOCAL3 -\brief Use this for local use. +/*! + \def LOG_LOCAL3 + \brief Use this for local use. */ -/*! \def LOG_LOCAL4 -\brief Use this for local use. +/*! + \def LOG_LOCAL4 + \brief Use this for local use. */ -/*! \def LOG_LOCAL5 -\brief Use this for local use. +/*! + \def LOG_LOCAL5 + \brief Use this for local use. */ -/*! \def LOG_LOCAL6 -\brief Use this for local use. +/*! + \def LOG_LOCAL6 + \brief Use this for local use. */ -/*! \def LOG_LOCAL7 -\brief Use this for local use. +/*! + \def LOG_LOCAL7 + \brief Use this for local use. */ //! @} -/*! @{ +/*! \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_ERR + \brief Errors */ -/*! \def LOG_WARNING -\brief Warnings +/*! + \def LOG_WARNING + \brief Warnings */ -/*! \def LOG_NOTICE -\brief Notices, instructions on how to use certain configuration options. +/*! + \def LOG_NOTICE + \brief Notices, instructions on how to use certain configuration options. */ -/*! \def LOG_INFO -\brief Information, like versions and so. +/*! + \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() */ \ No newline at end of file diff --git a/docs/user/support/typeconstants.dox b/docs/user/support/typeconstants.dox index ac1a212422..bf85966208 100644 --- a/docs/user/support/typeconstants.dox +++ b/docs/user/support/typeconstants.dox @@ -1,173 +1,185 @@ -/*! -\file TypeConstants.h -\ingroup support -\brief Represents typecodes that are used in various part of the Haiku API. +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Niels Sascha Reedijk + * Corresponds to: + * /trunk/headers/os/support/TypeConstants.h rev 20212 + */ -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. +/*! + \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. + \var B_ANY_TYPE + \brief General type when the exact contents is not yet known. */ /*! -\var B_ATOM_TYPE -\brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. + \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_ATOMREF_TYPE + \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. */ /*! -\var B_BOOL_TYPE -\brief Boolean value. + \var B_BOOL_TYPE + \brief Boolean value. */ /*! -\var B_CHAR_TYPE -\brief Represents the \c char type. + \var B_CHAR_TYPE + \brief Represents the \c char type. */ /*! -\var B_COLOR_8_BIT_TYPE -\brief Represents a one-byte colour. + \var B_COLOR_8_BIT_TYPE + \brief Represents a one-byte colour. */ /*! -\var B_DOUBLE_TYPE -\brief Represents the \c double type. + \var B_DOUBLE_TYPE + \brief Represents the \c double type. */ /*! -\var B_FLOAT_TYPE -\brief Represents the \c float type. + \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_GRAYSCALE_8_BIT_TYPE + \brief Represents a byte-long grayscale value. */ /*! -\var B_INT16_TYPE -\brief Represents a \c short type. + \var B_INT16_TYPE + \brief Represents a \c short type. */ /*! -\var B_INT32_TYPE -\brief Represents a \c long 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_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_INT8_TYPE + \brief Represents a \c char type used for integer storage. */ /*! -\var B_LARGE_ICON_TYPE -\brief Represents a large icon. + \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_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_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_MEDIA_PARAMETER_WEB_TYPE + \brief Represents the BParameterWeb type from the media kit. */ /*! -\var B_MESSAGE_TYPE -\brief Represents a BMessage type. + \var B_MESSAGE_TYPE + \brief Represents a BMessage type. */ /*! -\var B_MESSENGER_TYPE -\brief Represents a BMessenger type. + \var B_MESSENGER_TYPE + \brief Represents a BMessenger type. */ // Todo: the rest of the types -/*! @{ +/*! \name System-wide MIME types for handling URLs */ +//! @{ + /*! -\var B_URL_HTTP -\brief application/x-vnd.Be.URL.http + \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_HTTPS + \brief application/x-vnd.Be.URL.https */ /*! -\var B_URL_FTP -\brief application/x-vnd.Be.URL.ftp + \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_GOPHER + \brief application/x-vnd.Be.URL.gopher */ /*! -\var B_URL_MAILTO -\brief application/x-vnd.Be.URL.mailto + \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_NEWS + \brief application/x-vnd.Be.URL.news */ /*! -\var B_URL_NNTP -\brief application/x-vnd.Be.URL.nntp + \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_TELNET + \brief application/x-vnd.Be.URL.telnet */ /*! -\var B_URL_RLOGIN -\brief application/x-vnd.Be.URL.rlogin + \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_TN3270 + \brief application/x-vnd.Be.URL.tn3270 */ /*! -\var B_URL_WAIS -\brief application/x-vnd.Be.URL.wais + \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_FILE + \brief application/x-vnd.Be.URL.file */ //! @}