Revision: 9100
http://playerstage.svn.sourceforge.net/playerstage/?rev=9100&view=rev
Author: jpgr87
Date: 2012-07-07 17:41:46 +0000 (Sat, 07 Jul 2012)
Log Message:
-----------
playerc++ documentation improvements
Modified Paths:
--------------
code/player/trunk/client_libs/libplayerc++/clientproxy.h
code/player/trunk/client_libs/libplayerc++/playerclient.h
code/player/trunk/cmake/internal/FindOS.cmake
code/player/trunk/cmake/internal/LibraryUtils.cmake
code/player/trunk/cmake/internal/SetupDirectories.cmake
code/player/trunk/libplayerinterface/addr_util.h
code/player/trunk/libplayerinterface/interface_util.h
code/player/trunk/libplayerinterface/player.h
Modified: code/player/trunk/client_libs/libplayerc++/clientproxy.h
===================================================================
--- code/player/trunk/client_libs/libplayerc++/clientproxy.h 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/client_libs/libplayerc++/clientproxy.h 2012-07-07 17:41:46 UTC (rev 9100)
@@ -38,7 +38,7 @@
********************************************************************/
/***************************************************************************
- * Desc: Player v2.0 C++ client
+ * Desc: Player C++ client
* Authors: Brad Kratochvil, Toby Collett
*
* Date: 23 Sep 2005
@@ -83,7 +83,7 @@
public:
#ifdef HAVE_BOOST_SIGNALS
- /// A connection type. This is usefull when attaching signals to the
+ /// A connection type. This is useful when attaching signals to the
/// ClientProxy because it allows for detatching the signals.
typedef boost::signals::connection connection_t;
@@ -188,37 +188,73 @@
public:
- /// Returns true if we have received any data from the device.
+ /// @brief Proxy has any information
+ ///
+ /// This function can be used to see if any data has been received
+ /// from the driver since the ClientProxy was created.
+ ///
+ /// @return true if we have received any data from the device.
bool IsValid() const { return 0!=GetVar(mInfo->datatime); };
+ /// @brief Check for fresh data.
+ ///
/// Fresh is set to true on each new read. It is up to the user to
- /// set it to false if the data has already been read. This is most
- /// useful when used in conjunction with the PlayerMultiClient
+ /// set it to false if the data has already been read, by using @ref NotFresh()
+ /// This is most useful when used in conjunction with the PlayerMultiClient
+ ///
+ /// @return True if new data was read since the Fresh flag was last set false
bool IsFresh() const { return GetVar(mFresh); };
- /// This states that the data in a client is currently not Fresh
+ /// @brief Reset Fresh flag
+ ///
+ /// This sets the client's "Fresh" flag to false. After this is called,
+ /// @ref IsFresh() will return false until new information is available
+ /// after a call to a @ref Read() method.
void NotFresh();
- /// Returns the driver name
- /// @todo GetDriverName isn't guarded by locks yet
+ /// @brief Get the underlying driver's name
+ ///
+ /// Get the name of the driver that the ClientProxy is connected to.
+ ///
+ /// @return Driver name
+ /// @todo GetDriverName isn't guarded by locks yet
std::string GetDriverName() const { return mInfo->drivername; };
- /// Returns the received timestamp [s]
+ /// Returns the received timestamp of the last data sample [s]
double GetDataTime() const { return GetVar(mInfo->datatime); };
- /// Returns the received timestamp [s]
+ /// Returns the time between the current data time and the time of
+ /// the last data sample [s]
double GetElapsedTime() const
{ return GetVar(mInfo->datatime) - GetVar(mInfo->lasttime); };
- /// Returns a pointer to the Player Client
+ /// @brief Get a pointer to the Player Client
+ ///
+ /// Returns a pointer to the PlayerClient object that this client proxy
+ /// is connected through.
PlayerClient * GetPlayerClient() const { return mPc;}
- /// Returns device index
+
+ /// @brief Get device index
+ ///
+ /// Returns the device index of the interface the ClientProxy object
+ /// is connected to.
+ ///
+ /// @return interface's device index
uint32_t GetIndex() const { return GetVar(mInfo->addr.index); };
- /// Returns device interface
+ /// @brief Get Interface Code
+ ///
+ /// Get the interface code of the underlying proxy. See @ref message_codes for
+ /// a list of supported interface codes.
+ ///
+ /// @return Interface code
uint32_t GetInterface() const { return GetVar(mInfo->addr.interf); };
- /// Returns device interface
+ /// @brief Get Interface Name
+ ///
+ /// Get the interface type of the proxy as a string.
+ ///
+ /// @return Interface name
std::string GetInterfaceStr() const
{ return interf_to_str(GetVar(mInfo->addr.interf)); };
@@ -226,6 +262,7 @@
///
/// If a rule with the same pattern already exists, it will be replaced
/// with the new rule (i.e., its setting to replace will be updated).
+ ///
/// @param aReplace Should we replace these messages
/// @param aType The type to set replace rule for (-1 for wildcard),
/// see @ref message_types.
@@ -243,33 +280,97 @@
///
/// Send a message asking if the device supports the given message
/// type and subtype. If it does, the return value will be 1, and 0 otherwise.
+ ///
+ /// @param aType The capability type
+ /// @param aSubtype The capability subtype
+ /// @return 1 if capability is supported, 0 otherwise.
int HasCapability(uint32_t aType, uint32_t aSubtype);
/// @brief Request a boolean property
+ ///
+ /// Request a boolean property from the driver. If the has the property requested,
+ /// the current value of the property will be returned.
+ ///
+ /// @param[in] aProperty String containing the desired property name
+ /// @param[out] aValue Value of the requested property, if available
+ /// @return 0 If property request was successful, nonzero otherwise
int GetBoolProp(char *aProperty, bool *aValue);
/// @brief Set a boolean property
+ ///
+ /// Set a boolean property to a given value in the driver. If the property exists and
+ /// can be set, it will be set to the new value.
+ ///
+ /// @param[in] aProperty String containing the property name
+ /// @param aValue The value to set the property to
+ /// @return 0 if property change was successful, nonzero otherwise
int SetBoolProp(char *aProperty, bool aValue);
/// @brief Request an integer property
+ ///
+ /// Request an integer property from the driver. If the has the property requested,
+ /// the current value of the property will be returned.
+ ///
+ /// @param[in] aProperty String containing the desired property name
+ /// @param[out] aValue Value of the requested property, if available
+ /// @return 0 If property request was successful, nonzero otherwise.
int GetIntProp(char *aProperty, int32_t *aValue);
/// @brief Set an integer property
+ ///
+ /// Set an integer property to a given value in the driver. If the property exists and
+ /// can be set, it will be set to the new value.
+ ///
+ /// @param[in] aProperty String containing the property name
+ /// @param aValue The value to set the property to
+ /// @return 0 if property change was successful, nonzero otherwise
int SetIntProp(char *aProperty, int32_t aValue);
/// @brief Request a double property
+ ///
+ /// Request a double property from the driver. If the has the property requested,
+ /// the current value of the property will be returned.
+ ///
+ /// @param[in] aProperty String containing the desired property name
+ /// @param[out] aValue Value of the requested property, if available
+ /// @return 0 If property request was successful, nonzero otherwise.
int GetDblProp(char *aProperty, double *aValue);
/// @brief Set a double property
+ ///
+ /// Set an integer property to a given value in the driver. If the property exists and
+ /// can be set, it will be set to the new value.
+ ///
+ /// @param[in] aProperty String containing the property name
+ /// @param aValue The value to set the property to
+ /// @return 0 if property change was successful, nonzero otherwise
int SetDblProp(char *aProperty, double aValue);
/// @brief Request a string property
+ ///
+ /// Request a double property from the driver. If the has the property requested,
+ /// the current value of the property will be returned.
+ ///
+ /// @param[in] aProperty String containing the desired property name
+ /// @param[out] aValue Value of the requested property, if available
+ /// @return 0 If property request was successful, nonzero otherwise.
int GetStrProp(char *aProperty, char **aValue);
/// @brief Set a string property
+ ///
+ /// Set a string property to a given value in the driver. If the property exists and
+ /// can be set, it will be set to the new value.
+ ///
+ /// @param[in] aProperty String containing the property name
+ /// @param aValue The value to set the property to
+ /// @return 0 if property change was successful, nonzero otherwise
int SetStrProp(char *aProperty, char *aValue);
- /// Connect a signal to this proxy
+ /// @brief Connect a read signal to this proxy
+ ///
+ /// Connects a signal to the proxy to trigger. This functionality depends on
+ /// boost::signals, and will fail if Player was not compiled against the boost
+ /// signal library.
/// For more information check out @ref player_clientlib_multi
template<typename T>
connection_t ConnectReadSignal(T aSubscriber)
@@ -282,7 +383,10 @@
#endif
}
- /// Disconnect a signal to this proxy
+ /// @brief Disconnect a signal from this proxy
+ ///
+ /// Disconnects a connected read signal from the proxy
+ /// For more information check out @ref player_clientlib_multi
void DisconnectReadSignal(connection_t aSubscriber)
{
#ifdef HAVE_BOOST_SIGNALS
Modified: code/player/trunk/client_libs/libplayerc++/playerclient.h
===================================================================
--- code/player/trunk/client_libs/libplayerc++/playerclient.h 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/client_libs/libplayerc++/playerclient.h 2012-07-07 17:41:46 UTC (rev 9100)
@@ -166,10 +166,13 @@
/// destructor
~PlayerClient();
- /// Are we currently connected?
+ /// @brief Query connection to Player server
+ ///
+ /// Check if the PlayerClient is currently connected to the server.
+ /// @return true if connected, false if not.
bool Connected() { return (NULL!=mClient && mClient->connected == 1) ? true : false; }
- /// A mutex for handling synchronization
+ /// @brief A mutex for handling synchronization
mutex_t mMutex;
// ideally, we'd use the read_write mutex, but I was having some problems
@@ -268,7 +271,7 @@
/// This can be used to set the replace rule for all members of a
/// certain interface type. See @ref interfaces.
///
- /// @exception throws PlayerError if unsuccessfull
+ /// @exception throws PlayerError if unsuccessful
///
/// @see ClientProxy::SetReplaceRule, PlayerClient::SetDataMode
void SetReplaceRule(bool aReplace,
Modified: code/player/trunk/cmake/internal/FindOS.cmake
===================================================================
--- code/player/trunk/cmake/internal/FindOS.cmake 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/cmake/internal/FindOS.cmake 2012-07-07 17:41:46 UTC (rev 9100)
@@ -45,11 +45,6 @@
ENDIF (PLAYER_OS_LINUX)
-##RJM 10/09
-#SET (PLAYER_PROC_64BIT FALSE BOOL INTERNAL)
-#SET (PLAYER_PROC_PPC64 FALSE BOOL INTERNAL)
-#SET (PLAYER_PROC_X86_64 FALSE BOOL INTERNAL)
-
MESSAGE (STATUS "Got System Processor ${CMAKE_SYSTEM_PROCESSOR}")
# 32 or 64 bit Linux
Modified: code/player/trunk/cmake/internal/LibraryUtils.cmake
===================================================================
--- code/player/trunk/cmake/internal/LibraryUtils.cmake 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/cmake/internal/LibraryUtils.cmake 2012-07-07 17:41:46 UTC (rev 9100)
@@ -18,7 +18,10 @@
INSTALL_NAME_DIR ${RPATH_VAL}
INSTALL_RPATH "${INSTALL_RPATH};${CMAKE_INSTALL_PREFIX}/${PLAYER_LIBRARY_INSTALL_DIR}"
BUILD_WITH_INSTALL_RPATH TRUE)
- INSTALL (TARGETS ${_name} DESTINATION ${PLAYER_LIBRARY_INSTALL_DIR}/ COMPONENT libraries)
+ INSTALL (TARGETS ${_name} RUNTIME DESTINATION bin/
+ LIBRARY DESTINATION ${PLAYER_LIBRARY_INSTALL_DIR}/
+ ARCHIVE DESTINATION ${PLAYER_LIBRARY_INSTALL_DIR}/
+ COMPONENT libraries)
ENDMACRO (PLAYER_ADD_LIBRARY)
Modified: code/player/trunk/cmake/internal/SetupDirectories.cmake
===================================================================
--- code/player/trunk/cmake/internal/SetupDirectories.cmake 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/cmake/internal/SetupDirectories.cmake 2012-07-07 17:41:46 UTC (rev 9100)
@@ -1,8 +1,8 @@
# Default installation directory, based on operating system
IF (PLAYER_OS_WIN)
- SET (CMAKE_INSTALL_PREFIX "C:\\Program Files\\Player" CACHE PATH "Installation directory")
+ SET (CMAKE_INSTALL_PREFIX "C:\\Program Files\\Player" CACHE PATH "Installation prefix")
ELSE (PLAYER_OS_WIN)
- SET (CMAKE_INSTALL_PREFIX "/usr/local" CACHE PATH "Installation directory")
+ SET (CMAKE_INSTALL_PREFIX "/usr/local" CACHE PATH "Installation prefix")
ENDIF (PLAYER_OS_WIN)
MESSAGE (STATUS "Player will be installed to ${CMAKE_INSTALL_PREFIX}")
@@ -11,11 +11,13 @@
STRING (TOLOWER ${PROJECT_NAME} projectNameLower)
SET (PLAYER_INCLUDE_INSTALL_DIR "include/${projectNameLower}-${PLAYER_MAJOR_VERSION}.${PLAYER_MINOR_VERSION}")
-IF (PLAYER_PROC_64BIT)
- SET (LIB_SUFFIX "64" CACHE STRING "Suffix for library installation directory")
-ELSE (PLAYER_PROC_64BIT)
- SET (LIB_SUFFIX "" CACHE STRING "Suffix for library installation directory")
-ENDIF (PLAYER_PROC_64BIT)
+# Let the user take care of this
+SET(LIB_SUFFIX "" CACHE STRING "Suffix for library installation directory")
+#IF (PLAYER_PROC_64BIT)
+# SET (LIB_SUFFIX "64" CACHE STRING "Suffix for library installation directory")
+#ELSE (PLAYER_PROC_64BIT)
+# SET (LIB_SUFFIX "" CACHE STRING "Suffix for library installation directory")
+#ENDIF (PLAYER_PROC_64BIT)
SET (PLAYER_LIBRARY_INSTALL_DIR "lib${LIB_SUFFIX}")
Modified: code/player/trunk/libplayerinterface/addr_util.h
===================================================================
--- code/player/trunk/libplayerinterface/addr_util.h 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/libplayerinterface/addr_util.h 2012-07-07 17:41:46 UTC (rev 9100)
@@ -39,6 +39,11 @@
#ifndef _ADDR_UTIL_H
#define _ADDR_UTIL_H
+/** @ingroup libplayerinterface
+ @defgroup addrutil Address Utilities
+Utilities for converting between IP address formats.
+*/
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -56,10 +61,20 @@
#else
#define PLAYERINTERFACE_EXPORT
#endif
-
+/** @ingroup addrutil
+@{
+*/
+/// Convert a packed address to a dotted IP address string
+/// @param dest The destination buffer for the IP address string
+/// @param len The length of the destination buffer
+/// @param addr The packed address to be converted
PLAYERINTERFACE_EXPORT void packedaddr_to_dottedip(char* dest, size_t len, uint32_t addr);
+/// Convert a hostname to a packed IP address
+/// @param dest The destination for the packed IP address
+/// @param hostname The null-terminated string containing the host name.
+// @return 0 if successful, nonzero otherwise
PLAYERINTERFACE_EXPORT int hostname_to_packedaddr(uint32_t* dest, const char* hostname);
-
+/** @} */
#ifdef __cplusplus
}
#endif
Modified: code/player/trunk/libplayerinterface/interface_util.h
===================================================================
--- code/player/trunk/libplayerinterface/interface_util.h 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/libplayerinterface/interface_util.h 2012-07-07 17:41:46 UTC (rev 9100)
@@ -38,8 +38,11 @@
********************************************************************/
/** @ingroup libplayerinterface
-@{ */
+ @defgroup interfaceutil Interface Utilities
+These utilities are provided to make it easier to work with interface types.
+*/
+
#ifndef _INTERFACE_UTIL_H
#define _INTERFACE_UTIL_H
@@ -60,44 +63,46 @@
#ifdef __cplusplus
extern "C" {
#endif
+/** @ingroup interfaceutil
+@{ */
-// available interfaces are stored in an array of these, defined in
-// interface_util.c
+/// Available interfaces are stored in an array of these, defined in
+/// interface_util.c
typedef struct
{
uint16_t interf;
char* name;
} player_interface_t;
-/*
+/**
* Initialises the interface names/codes table.
*/
PLAYERINTERFACE_EXPORT int itable_init (void);
-/*
+/**
* Grows the interface table to newSize, filling each interface between the
* old end and the new end with (0xFFFF, "nointerfXX").
*/
PLAYERINTERFACE_EXPORT int itable_grow (int newSize);
-/*
+/**
* Destroys the interface names/codes table.
*/
PLAYERINTERFACE_EXPORT void itable_destroy (void);
-/*
+/**
* Add a new interface to the interface table.
*/
PLAYERINTERFACE_EXPORT int itable_add (const char *name, unsigned int code, int replace);
-/*
+/**
* looks through the array of available interfaces for one which the given
* name. if found, interface is filled out (the caller must provide storage)
* and zero is returned. otherwise, -1 is returned.
*/
PLAYERINTERFACE_EXPORT int lookup_interface(const char* name, player_interface_t* interf);
-/*
+/**
* looks through the array of available interfaces for one which the given
* code. if found, interface is filled out (the caller must provide storage)
* and zero is returned. otherwise, -1 is returned.
@@ -105,7 +110,7 @@
PLAYERINTERFACE_EXPORT int
lookup_interface_code(int code, player_interface_t* interf);
-/*
+/**
* looks through the array of interfaces, starting at startpos, for the first
* entry that has the given code, and returns the name.
* returns 0 if the device is not found.
@@ -113,38 +118,36 @@
PLAYERINTERFACE_EXPORT const char*
lookup_interface_name(unsigned int startpos, int code);
-/*
+/**
* Returns the name of an interface given its code. The result string must
* not be altered.
*/
PLAYERINTERFACE_EXPORT const char*
interf_to_str(uint16_t code);
-/*
+/**
* Returns the code for an interface, given a string. If the name is not found,
* 0xFFFF is returned.
*/
PLAYERINTERFACE_EXPORT uint16_t
str_to_interf(const char *name);
-/*
+/**
* Returns the name of a message type given its code. The result string must
* not be altered.
*/
PLAYERINTERFACE_EXPORT const char*
msgtype_to_str(uint8_t code);
-/*
+/**
* Returns the code for a message type, given a string. If the name is not
* found, 0xFF is returned.
*/
PLAYERINTERFACE_EXPORT uint8_t
str_to_msgtype(const char *name);
-
+/** @} */
#ifdef __cplusplus
}
#endif
+#endif
-/** @} */
-
-#endif
Modified: code/player/trunk/libplayerinterface/player.h
===================================================================
--- code/player/trunk/libplayerinterface/player.h 2012-07-07 17:39:37 UTC (rev 9099)
+++ code/player/trunk/libplayerinterface/player.h 2012-07-07 17:41:46 UTC (rev 9100)
@@ -385,13 +385,18 @@
The HANDLE_CAPABILITY_REQUEST macro (from driver.h) can be used to make this process
simpler, an example call would be something like this at the start of ProcessMessage
+@verbatim
HANDLE_CAPABILITY_REQUEST (position_id, resp_queue, hdr, data, PLAYER_MSGTYPE_REQ, PLAYER_CAPABILITIES_REQ);
HANDLE_CAPABILITY_REQUEST (position_id, resp_queue, hdr, data, PLAYER_MSGTYPE_CMD, PLAYER_POSITION2D_CMD_VEL);
+@endverbatim
+@{
*/
+/// Capability request message type
#define PLAYER_CAPABILITIES_REQ 255
-//misspelled version, for backwards compatibility with v3.0.2 (will be removed in v4.0
+/// Capability request message type
+/// (Misspelled for backwards compatibility with v3.0.2 and earler, will be removed in v4.0)
#define PLAYER_CAPABILTIES_REQ 255
/** @brief Structure containing a single capability request */
@@ -403,21 +408,39 @@
uint32_t subtype;
} player_capabilities_req_t;
+/** @} */
+
/**
@ingroup message_basics
@defgroup propbags Property Bags
Querying driver properties
+All drivers will respond to requests for driver properties.
+
+If a driver implements a configuration option as a driver property, then the driver property
+is available to get and set while the driver is running. Driver properties are a solution to static configuration
+file options which force the Player server to be stopped before a driver's configuration can be changed.
+
+Driver properties are implemented as four basic types: IntProp, DoubleProp, StringProp, and BoolProp.
+@{
*/
+/// Integer property get request subtype
#define PLAYER_GET_INTPROP_REQ 254
+/// Integer property set request subtype
#define PLAYER_SET_INTPROP_REQ 253
+/// Double property get request subtype
#define PLAYER_GET_DBLPROP_REQ 252
+/// Double property set request subtype
#define PLAYER_SET_DBLPROP_REQ 251
+/// String property get request subtype
#define PLAYER_GET_STRPROP_REQ 250
+/// String property set request subtype
#define PLAYER_SET_STRPROP_REQ 249
+/// Boolean property get request subtype
#define PLAYER_GET_BOOLPROP_REQ 248
+/// Boolean property get request subtype
#define PLAYER_SET_BOOLPROP_REQ 247
/** @brief Request to get a boolean property */
@@ -433,39 +456,42 @@
/** @brief Request to get an integer property */
typedef struct player_intprop_req
+
{
- /** The property key's length */
- uint32_t key_count;
- /** The property key */
- char *key;
- /** The property value */
- int32_t value;
+ /** The property key's length */
+ uint32_t key_count;
+ /** The property key */
+ char *key;
+ /** The property value */
+ int32_t value;
} player_intprop_req_t;
/** @brief Request to get a double property */
typedef struct player_dblprop_req
{
- /** The property key's length */
- uint32_t key_count;
- /** The property key */
- char *key;
- /** The property value */
- double value;
+ /** The property key's length */
+ uint32_t key_count;
+ /** The property key */
+ char *key;
+ /** The property value */
+ double value;
} player_dblprop_req_t;
/** @brief Request to get a string property */
typedef struct player_strprop_req
{
- /** The property key's length */
- uint32_t key_count;
- /** The property key */
- char *key;
- /** The property's length */
- uint32_t value_count;
- /** The property value */
- char *value;
+ /** The property key's length */
+ uint32_t key_count;
+ /** The property key */
+ char *key;
+ /** The property's length */
+ uint32_t value_count;
+ /** The property value */
+ char *value;
} player_strprop_req_t;
+/** @} */
+
// /////////////////////////////////////////////////////////////////////////////
//
// Here starts the alphabetical list of interfaces
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|