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.
------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
_______________________________________________
Playerstage-commit mailing list
Playerstage-commit@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/playerstage-commit
