Skip to content

Commit

Permalink
Format document.
Browse files Browse the repository at this point in the history
  • Loading branch information
@pawel-soja
pawel-soja committed May 10, 2021
1 parent 55f8436 commit 946b958
Showing 1 changed file with 62 additions and 65 deletions.
127 changes: 62 additions & 65 deletions libs/indibase/basedevice.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,14 @@

// #define MAXRBUF 2048 // #PS: defined in indibase.h

/**
* \class INDI::BaseDevice
* \brief Class to provide basic INDI device functionality.
/** @class INDI::BaseDevice
* @brief Class to provide basic INDI device functionality.
*
* INDI::BaseDevice is the base device for all INDI devices and contains a list of all properties defined by the device either explicity or via a skeleton file.
* You don't need to subclass INDI::BaseDevice class directly, it is inheritied by INDI::DefaultDevice which takes care of building a standard INDI device. Moreover, INDI::BaseClient
* maintains a list of INDI::BaseDevice objects as they get defined from the INDI server, and those objects may be accessed to retrieve information on the object properties or message log.
* INDI::BaseDevice is the base device for all INDI devices and contains a list of all properties defined by the device either explicity or via a skeleton file.
* You don't need to subclass INDI::BaseDevice class directly, it is inheritied by INDI::DefaultDevice which takes care of building a standard INDI device. Moreover, INDI::BaseClient
* maintains a list of INDI::BaseDevice objects as they get defined from the INDI server, and those objects may be accessed to retrieve information on the object properties or message log.
*
* \author Jasem Mutlaq
* @author Jasem Mutlaq
*/
namespace INDI
{
Expand Down Expand Up @@ -65,9 +64,7 @@ class BaseDevice
INDI_DISABLED
};

/**
* @brief The DRIVER_INTERFACE enum defines the class of devices the driver implements. A driver may implement one or more interfaces.
*/
/** @brief The DRIVER_INTERFACE enum defines the class of devices the driver implements. A driver may implement one or more interfaces. */
enum DRIVER_INTERFACE
{
GENERAL_INTERFACE = 0, /**< Default interface for all INDI devices */
Expand Down Expand Up @@ -95,21 +92,21 @@ class BaseDevice
virtual ~BaseDevice();

public:
/** \return Return vector number property given its name */
/** @return Return vector number property given its name */
INDI::PropertyView<INumber> *getNumber(const char *name) const;
/** \return Return vector text property given its name */
/** @return Return vector text property given its name */
INDI::PropertyView<IText> *getText(const char *name) const;
/** \return Return vector switch property given its name */
/** @return Return vector switch property given its name */
INDI::PropertyView<ISwitch> *getSwitch(const char *name) const;
/** \return Return vector light property given its name */
/** @return Return vector light property given its name */
INDI::PropertyView<ILight> *getLight(const char *name) const;
/** \return Return vector BLOB property given its name */
/** @return Return vector BLOB property given its name */
INDI::PropertyView<IBLOB> *getBLOB(const char *name) const;

public:
/** \return Return property state */
/** @return Return property state */
IPState getPropertyState(const char *name) const;
/** \return Return property permission */
/** @return Return property permission */
IPerm getPropertyPermission(const char *name) const;

public:
Expand All @@ -130,66 +127,66 @@ class BaseDevice

void registerProperty(INDI::Property &property);

/** \brief Remove a property
* \param name name of property to be removed. Pass NULL to remove the whole device.
* \param errmsg buffer to store error message.
* \return 0 if successul, -1 otherwise.
/** @brief Remove a property
* @param name name of property to be removed. Pass NULL to remove the whole device.
* @param errmsg buffer to store error message.
* @return 0 if successul, -1 otherwise.
*/
int removeProperty(const char *name, char *errmsg);

/** \brief Return a property and its type given its name.
* \param name of property to be found.
* \param type of property found.
* \return If property is found, the raw void * pointer to the IXXXVectorProperty is returned. To be used you must use static_cast with given the type of property
/** @brief Return a property and its type given its name.
* @param name of property to be found.
* @param type of property found.
* @return If property is found, the raw void * pointer to the IXXXVectorProperty is returned. To be used you must use static_cast with given the type of property
* returned. For example, INumberVectorProperty *num = static_cast<INumberVectorProperty> getRawProperty("FOO", INDI_NUMBER);
*
* \note This is a low-level function and should not be called directly unless necessary. Use getXXX instead where XXX
* @note This is a low-level function and should not be called directly unless necessary. Use getXXX instead where XXX
* is the property type (Number, Text, Switch..etc).
*/
void *getRawProperty(const char *name, INDI_PROPERTY_TYPE type = INDI_UNKNOWN) const;

/** \brief Return a property and its type given its name.
* \param name of property to be found.
* \param type of property found.
* \return If property is found, it is returned. To be used you must use static_cast with given the type of property
/** @brief Return a property and its type given its name.
* @param name of property to be found.
* @param type of property found.
* @return If property is found, it is returned. To be used you must use static_cast with given the type of property
* returned.
*/
Property *getProperty(const char *name, INDI_PROPERTY_TYPE type = INDI_UNKNOWN) const;

/** \brief Return a list of all properties in the device. */
/** @brief Return a list of all properties in the device. */
Properties *getProperties();
const Properties *getProperties() const;

public:
/** \brief Add message to the driver's message queue.
* \param msg Message to add.
/** @brief Add message to the driver's message queue.
* @param msg Message to add.
*/
void addMessage(const std::string &msg);
void checkMessage(XMLEle *root);
void doMessage(XMLEle *msg);

/** \return Returns a specific message. */
/** @return Returns a specific message. */
const std::string &messageQueue(size_t index) const;

/** \return Returns last message message. */
/** @return Returns last message message. */
const std::string &lastMessage() const;

public:
/** \return True if the device is connected (CONNECT=ON), False otherwise */
/** @return True if the device is connected (CONNECT=ON), False otherwise */
bool isConnected() const;

/** \brief Set the driver's mediator to receive notification of news devices and updated property values. */
/** @brief Set the driver's mediator to receive notification of news devices and updated property values. */
void setMediator(INDI::BaseMediator *mediator);

/** \returns Get the meditator assigned to this driver */
/** @returns Get the meditator assigned to this driver */
INDI::BaseMediator *getMediator() const;

/** \brief Set the device name
* \param dev new device name
/** @brief Set the device name
* @param dev new device name
*/
void setDeviceName(const char *dev);

/** \return Returns the device name */
/** @return Returns the device name */
const char *getDeviceName() const;

/** @brief Check that the device name matches the argument. **/
Expand All @@ -198,54 +195,54 @@ class BaseDevice
/** @brief Check that the device name matches the argument. **/
bool isDeviceNameMatch(const std::string &otherName) const;

/** \return driver name
* \note This can only be valid if DRIVER_INFO is defined by the driver.
/** @return driver name
* @note This can only be valid if DRIVER_INFO is defined by the driver.
*/
const char *getDriverName() const;

/** \return driver executable name
* \note This can only be valid if DRIVER_INFO is defined by the driver.
/** @return driver executable name
* @note This can only be valid if DRIVER_INFO is defined by the driver.
*/
const char *getDriverExec() const;

/** \return driver version
* \note This can only be valid if DRIVER_INFO is defined by the driver.
/** @return driver version
* @note This can only be valid if DRIVER_INFO is defined by the driver.
*/
const char *getDriverVersion() const;

/**
* @brief getDriverInterface returns ORed values of @ref INDI::BaseDevice::DRIVER_INTERFACE "DRIVER_INTERFACE". It presents the device classes supported by the driver.
* @return driver device interface descriptor.
* @note For example, to know if the driver supports CCD interface, check the retruned value:
* @code{.cpp}
* if (device->getDriverInterface() & CCD_INTERFACE)
* cout << "We received a camera!" << endl;
* @endcode
/** @brief getDriverInterface returns ORed values of @ref INDI::BaseDevice::DRIVER_INTERFACE "DRIVER_INTERFACE". It presents the device classes supported by the driver.
* @return driver device interface descriptor.
* @note For example, to know if the driver supports CCD interface, check the retruned value:
* @code{.cpp}
* if (device->getDriverInterface() & CCD_INTERFACE)
* cout << "We received a camera!" << endl;
* @endcode
*/
virtual uint16_t getDriverInterface();

public:
/** \brief Build driver properties from a skeleton file.
* \param filename full path name of the file.
* \return true if successful, false otherwise.
/** @brief Build driver properties from a skeleton file.
* @param filename full path name of the file.
* @return true if successful, false otherwise.
*
* A skeloton file defines the properties supported by this driver. It is a list of defXXX elements enclosed by @<INDIDriver>@
* and @</INDIDriver>@ opening and closing tags. After the properties are created, they can be rerieved, manipulated, and defined
* to other clients.
* \see An example skeleton file can be found under examples/tutorial_four_sk.xml
* @see An example skeleton file can be found under examples/tutorial_four_sk.xml
*/
bool buildSkeleton(const char *filename);

/** \brief Build a property given the supplied XML element (defXXX)
* \param root XML element to parse and build.
* \param errmsg buffer to store error message in parsing fails.
* \return 0 if parsing is successful, -1 otherwise and errmsg is set
/** @brief Build a property given the supplied XML element (defXXX)
* @param root XML element to parse and build.
* @param errmsg buffer to store error message in parsing fails.
* @return 0 if parsing is successful, -1 otherwise and errmsg is set
*/
int buildProp(XMLEle *root, char *errmsg);

/** \brief handle SetXXX commands from client */
/** @brief handle SetXXX commands from client */
int setValue(XMLEle *root, char *errmsg);
/** \brief Parse and store BLOB in the respective vector */

/** @brief Parse and store BLOB in the respective vector */
int setBLOB(IBLOBVectorProperty *pp, XMLEle *root, char *errmsg);

protected:
Expand Down

0 comments on commit 946b958

Please sign in to comment.