Commit d8ae5d4d authored by Jon A. Cruz's avatar Jon A. Cruz

Corrected files with doxygen comments that were generating warnings.

Fixed several files with out of date or incorrect doxygen comments.
These included use of explicit tags (@fn, @var, @struct, etc.),
incorrect use of "[IN]" and "[OUT]", and other issues.

Aside from the problems actually marked in the output as warnings,
these issues were causing a large portion of the documentation to
be dropped silently.

Change-Id: I66027f4f98a6e82b7db826693b5ec1b1f30e58cf
Signed-off-by: default avatarJon A. Cruz <jonc@osg.samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/1836Reviewed-by: default avatarErich Keane <erich.keane@intel.com>
Reviewed-by: default avatarOssama Othman <ossama.othman@intel.com>
Tested-by: default avatarjenkins-iotivity <jenkins-iotivity@opendaylight.org>
parent 5fa5d4ef
......@@ -35,109 +35,93 @@ extern "C"
#endif /* __cplusplus */
/**
* @struct u_queue_message
* @brief Queue message format
* Queue message format.
*/
typedef struct u_queue_message_t
{
/* Pointer to message*/
/** Pointer to message. */
void *msg;
/* message size */
/** message size. */
uint32_t size;
} u_queue_message_t;
typedef struct u_queue_element_t u_queue_element;
/**
* @struct u_queue_element
* @brief Queue element format
* Queue element format.
*/
struct u_queue_element_t
{
/* pointer to queue message */
/** pointer to queue message. */
u_queue_message_t *message;
/* Pointer to next queue element*/
/** Pointer to next queue element. */
u_queue_element *next;
};
/**
* @struct u_queue_t
* @brief Queue structure
* Queue structure.
*/
typedef struct u_queue_t
{
/* Head of the queue */
/** Head of the queue. */
u_queue_element *element;
/* Number of messages in Queue*/
/** Number of messages in Queue. */
uint32_t count;
} u_queue_t;
/**
* @brief API to creates queue and initializes the elements.
* @return u_queue_t pointer if Success, NULL otherwise
* API to creates queue and initializes the elements.
* @return u_queue_t pointer if Success, NULL otherwise.
*/
u_queue_t *u_queue_create();
/**
* @fn u_queue_delete
* @brief Resets and deletes the queue
* @param queue- queue pointer
* @return CAResult_t - CA_STATUS_OK, if Success
* @return CA_STATUS_FAILED - otherwise
* Resets and deletes the queue.
* @param queue- queue pointer.
* @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
*/
CAResult_t u_queue_delete(u_queue_t *queue);
/**
* @fn u_queue_add_element
* @brief Adds message at the end of the queue
* @param queue - pointer to queue
* @param message - Pointer to message
* @return CAResult_t - CA_STATUS_OK, if Success
* @return CA_STATUS_FAILED - otherwise
* Adds message at the end of the queue.
* @param queue pointer to queue.
* @param message Pointer to message.
* @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
*/
CAResult_t u_queue_add_element(u_queue_t *queue, u_queue_message_t *message);
/**
* @fn u_queue_get_element
* @brief Returns the first message in the queue and removes queue element.
* Returns the first message in the queue and removes queue element.
* Head is moved to next element.
* @param queue - pointer to queue
* @return pointer to Message, if Success
* @return NULL - otherwise
* @param queue pointer to queue.
* @return pointer to Message if Success, NULL otherwise.
*/
u_queue_message_t *u_queue_get_element(u_queue_t *queue);
/**
* @fn u_queueRemoveElement
* @brief Removes head element of the queue
* @param queue - pointer to queue
* @return CAResult_t - CA_STATUS_OK, if Success
* @return CA_STATUS_FAILED - otherwise
* Removes head element of the queue.
* @param queue pointer to queue.
* @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
*/
CAResult_t u_queue_remove_element(u_queue_t *queue);
/**
* @fn u_queue_get_size
* @param queue - pointer to queue
* @return number of elements in queue
* @param queue pointer to queue.
* @return number of elements in queue.
*/
uint32_t u_queue_get_size(u_queue_t *queue);
/**
* @fn u_queue_reset
* @brief Removes all the messages from Queue and reset message count
* @param queue - pointer to queue
* @return CAResult_t - CA_STATUS_OK, if Success
* @return CA_STATUS_FAILED - otherwise
* Removes all the messages from Queue and reset message count.
* @param queue pointer to queue.
* @return ::CA_STATUS_OK if Success, ::CA_STATUS_FAILED otherwise.
*/
CAResult_t u_queue_reset(u_queue_t *queue);
/**
* @fn u_queue_get_head
* @brief Returns the first message in queue, but not remove the element
* @param queue - pointer to queue
* @return pointer to Message, if Success
* @return NULL - otherwise
* Returns the first message in queue, but not remove the element.
* @param queue pointer to queue.
* @return pointer to Message if Success, NULL otherwise.
*/
u_queue_message_t *u_queue_get_head(u_queue_t *queue);
......@@ -146,4 +130,3 @@ u_queue_message_t *u_queue_get_head(u_queue_t *queue);
#endif /* __cplusplus */
#endif /* U_QUEUE_H_ */
/******************************************************************
/* ****************************************************************
*
* Copyright 2014 Samsung Electronics All Rights Reserved.
*
......@@ -41,8 +41,8 @@ extern "C"
typedef enum
{
STATE_DISCONNECTED, /**< State is Disconnected */
STATE_CONNECTED /**< State is Connected */
STATE_DISCONNECTED, /**< State is Disconnected. */
STATE_CONNECTED /**< State is Connected. */
} CAConnectedState_t;
typedef struct connected_state
......@@ -52,253 +52,243 @@ typedef struct connected_state
} state_t;
/**
* @enum CAAdapterServerType_t
* @brief Enum for defining different server types.
* Enum for defining different server types.
*/
typedef enum
{
CA_UNICAST_SERVER = 0, /**< Unicast Server */
CA_MULTICAST_SERVER, /**< Multicast Server */
CA_SECURED_UNICAST_SERVER /**< Secured Unicast Server */
CA_UNICAST_SERVER = 0, /**< Unicast Server. */
CA_MULTICAST_SERVER, /**< Multicast Server. */
CA_SECURED_UNICAST_SERVER /**< Secured Unicast Server. */
} CAAdapterServerType_t;
/**
* @struct CAEDRData
* @brief Structure to maintain the information of data in message queue.
* Structure to maintain the information of data in message queue.
*/
typedef struct
{
CAEndpoint_t *remoteEndpoint; /**< Remote Endpoint */
void *data; /**< Data to be sent */
uint32_t dataLen; /**< Length of the data to be sent */
CAEndpoint_t *remoteEndpoint; /**< Remote Endpoint. */
void *data; /**< Data to be sent. */
uint32_t dataLen; /**< Length of the data to be sent. */
} CAEDRData;
/**
* @struct CAEDRNetworkEvent
* @brief Structure to maintain the adapter information and its status.
* Structure to maintain the adapter information and its status.
*/
typedef struct
{
CAEndpoint_t *info; /**< Local Connectivity Information */
CANetworkStatus_t status; /**< Network Status */
CAEndpoint_t *info; /**< Local Connectivity Information. */
CANetworkStatus_t status; /**< Network Status. */
} CAEDRNetworkEvent;
/**
* @brief This will be used during the recive of network requests and response.
* @param remoteAddress [IN] EDR address of remote OIC device from which data received.
* @param data [IN] Data received
* @param dataLength [IN] Length of the Data received
* @param sentLength [OUT] Length of the sent data
* @return NONE
* @pre Callback must be registered using CAEDRSetPacketReceivedCallback()
* This will be used during the recive of network requests and response.
* @param[in] remoteAddress EDR address of remote OIC device from which data received.
* @param[in] data Data received.
* @param[in] dataLength Length of the Data received.
* @param[out] sentLength Length of the sent data.
* @pre Callback must be registered using CAEDRSetPacketReceivedCallback().
*/
typedef void (*CAEDRDataReceivedCallback)(const char *remoteAddress, const void *data,
uint32_t dataLength, uint32_t *sentLength);
/**
* @brief This will be used during change in network status.
* @param status [IN] Network Status of the adapter
* @return NONE
* This will be used during change in network status.
* @param[in] status Network Status of the adapter.
*/
typedef void (*CAEDRNetworkStatusCallback)(CANetworkStatus_t status);
/**
* @brief Callback to notify the error in the EDR adapter
* @param remoteAddress [IN] Remote EDR Address
* @param serviceUUID [IN] Service UUID of the device
* @param data [IN] data containing token, uri and coap data
* @param dataLength [IN] length of data
* @param result [IN] error code as defined in CAResult_t
* @return NONE
* @pre Callback must be registered using CAEDRSetPacketReceivedCallback()
* Callback to notify the error in the EDR adapter.
* @param[in] remoteAddress Remote EDR Address.
* @param[in] serviceUUID Service UUID of the device.
* @param[in] data data containing token, uri and coap data.
* @param[in] dataLength length of data.
* @param[in] result error code as defined in ::CAResult_t.
* @pre Callback must be registered using CAEDRSetPacketReceivedCallback().
*/
typedef void (*CAEDRErrorHandleCallback)(const char *remoteAddress, const char *serviceUUID,
const void *data, uint32_t dataLength, CAResult_t result);
/**
* @brief Initialize the network monitor module
* @param threadPool [IN] Threadpool Handle
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_ADAPTER_NOT_ENABLED Initialization is successful, but bluetooth adapter is
* not enabled.
* @retval #CA_STATUS_FAILED Operation failed
* @see CAEDRTerminateNetworkMonitor()
* Initialize the network monitor module
* @param[in] threadPool Threadpool Handle.
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_ADAPTER_NOT_ENABLED Initialization is successful, but
* bluetooth adapter is not enabled.
* @retval ::CA_STATUS_FAILED Operation failed.
* @see CAEDRTerminateNetworkMonitor().
*/
CAResult_t CAEDRInitializeNetworkMonitor(const ca_thread_pool_t threadPool);
/**
* @brief Deinitialize with bluetooth adapter.
* @return NONE
* @pre CAEDRInitializeNetworkMonitor() should be invoked before using this API.
* @see CAEDRInitializeNetworkMonitor()
* Deinitialize with bluetooth adapter.
* @pre CAEDRInitializeNetworkMonitor() should be invoked before using
* this API.
* @see CAEDRInitializeNetworkMonitor().
*/
void CAEDRTerminateNetworkMonitor();
/**
* @brief Start Network Monitoring Process
* @return #CA_STATUS_OK or Appropriate error code
* Start Network Monitoring Process.
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRStartNetworkMonitor();
/**
* @brief Stop Network Monitoring Process
* @return #CA_STATUS_OK or Appropriate error code
* Stop Network Monitoring Process.
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRStopNetworkMonitor();
/**
* @brief Sets the callback and Starts discovery for nearby OIC bluetooth devices.
* Sets the callback and Starts discovery for nearby OIC bluetooth devices.
*
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_STATUS_FAILED Operation failed
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_STATUS_FAILED Operation failed.
*/
CAResult_t CAEDRClientSetCallbacks();
/**
* @brief Resetting callbacks with bluetooth framework and stop OIC device discovery.
* @return NONE
* Resetting callbacks with bluetooth framework and stop OIC device discovery.
* @pre CAEDRClientSetCallbacks() should be invoked before using this API.
* @see CAEDRClientSetCallbacks()
* @see CAEDRClientSetCallbacks().
*/
void CAEDRClientUnsetCallbacks();
/**
* @brief Used to initialize the EDR client module where mutex is initialized
* @return NONE
* Used to initialize the EDR client module where mutex is initialized.
*/
void CAEDRInitializeClient(ca_thread_pool_t handle);
/**
* @brief Destroys the Device list and mutex.
* @return NONE
* Destroys the Device list and mutex.
*/
void CAEDRClientTerminate();
/**
* @brief Closes all the client connection to peer bluetooth devices.
* @return NONE
* Closes all the client connection to peer bluetooth devices.
*/
void CAEDRClientDisconnectAll();
/**
* @brief Register callback to send the received packets from remote bluetooth device to BTAdapter.
* Register callback to send the received packets from remote bluetooth
* device to BTAdapter.
*
* @param packetReceivedCallback [IN] Callback function to register for sending network
* packets to EDR Adapter.
* @return NONE
* @param[in] packetReceivedCallback Callback function to register for
* sending network packets to EDR Adapter.
*/
void CAEDRSetPacketReceivedCallback(CAEDRDataReceivedCallback packetReceivedCallback);
/**
* @brief Register callback for receiving local bluetooth adapter state.
* Register callback for receiving local bluetooth adapter state.
*
* @param networkStateChangeCallback [IN] Callback function to register for receiving local
* bluetooth adapter status.
* @return NONE
* @param[in] networkStateChangeCallback Callback function to register
* for receiving local bluetooth adapter status.
*/
void CAEDRSetNetworkChangeCallback(CAEDRNetworkStatusCallback networkStateChangeCallback);
/**
* @brief set error callback to notify error in EDR adapter
* set error callback to notify error in EDR adapter.
*
* @param errorHandleCallback [IN] Callback function to notify the error in the EDR adapter
* @return NONE
* @param[in] errorHandleCallback Callback function to notify the error
* in the EDR adapter.
*/
void CAEDRSetErrorHandler(CAEDRErrorHandleCallback errorHandleCallback);
/**
* @brief Get the local bluetooth adapter information.
* Get the local bluetooth adapter information.
*
* @param info [OUT] Local bluetooth adapter information
* @param[out] info Local bluetooth adapter information.
*
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
* @retval #CA_STATUS_FAILED Operation failed
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_STATUS_INVALID_PARAM Invalid input argumets.
* @retval ::CA_STATUS_FAILED Operation failed.
*
* @see #CALocalConnectivity_t
* @see CALocalConnectivity_t
*
*/
CAResult_t CAEDRGetInterfaceInformation(CAEndpoint_t **info);
/**
* @brief Start RFCOMM server for given service UUID
* Start RFCOMM server for given service UUID
*
* @param serviceUUID [IN] The UUID of service with which RFCOMM server needs to be started.
* @param serverFD [IN] The RFCOMM server socket file descriptor.
* @param handle [IN] Threadpool Handle
* @param[in] serviceUUID The UUID of service with which RFCOMM server
* needs to be started.
* @param[in] serverFD The RFCOMM server socket file descriptor.
* @param[in] handle Threadpool Handle.
*
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_STATUS_INVALID_PARAM Invalid input argumets
* @retval #CA_STATUS_FAILED Operation failed
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_STATUS_INVALID_PARAM Invalid input argumets.
* @retval ::CA_STATUS_FAILED Operation failed.
*
*/
CAResult_t CAEDRServerStart(const char *serviceUUID, int *serverFD, ca_thread_pool_t handle);
/**
* @brief Stop RFCOMM server
* Stop RFCOMM server
*
* @param serverFD [IN] The RFCOMM server socket file descriptor which needs to be stopped.
* @param[in] serverFD The RFCOMM server socket file descriptor which
* needs to be stopped.
*
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_STATUS_FAILED Operation failed
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_STATUS_FAILED Operation failed.
*/
CAResult_t CAEDRServerStop(int serverFD);
/**
* @brief Terminate server for EDR
* @return None
* Terminate server for EDR.
*/
void CAEDRServerTerminate();
/**
* @brief All received data will be notified to upper layer.
* All received data will be notified to upper layer.
*
* @return #CA_STATUS_OK or Appropriate error code
* @retval #CA_STATUS_OK Successful
* @retval #CA_STATUS_FAILED Operation failed
* @return ::CA_STATUS_OK or Appropriate error code.
* @retval ::CA_STATUS_OK Successful.
* @retval ::CA_STATUS_FAILED Operation failed.
*
*/
CAResult_t CAEDRManagerReadData();
/**
* @brief This function gets bluetooth adapter enable state.
* @param state [OUT] State of the Adapter.
* @return #CA_STATUS_OK or Appropriate error code
* This function gets bluetooth adapter enable state.
* @param[out] state State of the Adapter.
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRGetAdapterEnableState(bool *state);
/**
* @brief This function sends data to specified remote bluetooth device.
* @param remoteAddress [IN] Remote EDR Address
* @param serviceUUID [IN] Service UUID of the device
* @param data [IN] Data to be sent
* @param dataLength [IN] Length of the data to be sent
* @param sentLength [OUT] Length of the actual sent data
* @return #CA_STATUS_OK or Appropriate error code
* This function sends data to specified remote bluetooth device.
* @param[in] remoteAddress Remote EDR Address.
* @param[in] serviceUUID Service UUID of the device.
* @param[in] data Data to be sent.
* @param[in] dataLength Length of the data to be sent.
* @param[out] sentLength Length of the actual sent data.
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRClientSendUnicastData(const char *remoteAddress, const char *serviceUUID,
const void *data, uint32_t dataLength, uint32_t *sentLength);
/**
* @brief This function sends data to all bluetooth devices running OIC service.
* @param serviceUUID [IN] Service UUID of the device
* @param data [IN] Data to be sent
* @param dataLength [IN] Length of the data to be sent
* @param sentLength [OUT] Length of the actual sent data
* @return #CA_STATUS_OK or Appropriate error code
* This function sends data to all bluetooth devices running OIC service.
* @param[in] serviceUUID Service UUID of the device.
* @param[in] data Data to be sent.
* @param[in] dataLength Length of the data to be sent.
* @param[out] sentLength Length of the actual sent data.
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRClientSendMulticastData(const char *serviceUUID, const void *data,
uint32_t dataLength, uint32_t *sentLength);
/**
* @brief This function gets bonded bluetooth device list
* @return #CA_STATUS_OK or Appropriate error code
* This function gets bonded bluetooth device list
* @return ::CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAEDRGetBondedDeviceList();
......@@ -307,4 +297,3 @@ CAResult_t CAEDRGetBondedDeviceList();
#endif
#endif /* CA_EDR_INTERFACE_H_ */
/******************************************************************
/* ****************************************************************
*
* Copyright 2014 Samsung Electronics All Rights Reserved.
*
......@@ -19,8 +19,8 @@
******************************************************************/
/**
* @file caipadapter.h
* @brief This file contains the APIs for IP Adapter.
* @file
* This file contains the APIs for IP Adapter.
*/
#ifndef CA_IP_ADAPTER_H_
#define CA_IP_ADAPTER_H_
......@@ -35,16 +35,17 @@ extern "C"
#endif
/**
* @brief API to initialize IP Interface.
* @param registerCallback [IN] Callback to register IP interfaces to Connectivity
* Abstraction Layer
* @param networkPacketCallback [IN] Callback to notify request and response messages from server(s)
* API to initialize IP Interface.
* @param[in] registerCallback Callback to register IP interfaces to
* Connectivity Abstraction Layer.
* @param[in] networkPacketCallback Callback to notify request and
* response messages from server(s)
* started at Connectivity Abstraction Layer.
* @param netCallback [IN] Callback to notify the network additions to Connectivity
* Abstraction Layer.
* @param errorCallback [IN] Callback to notify the network errors to Connectivity
* Abstraction Layer
* @param handle [IN] Threadpool Handle
* @param[in] netCallback Callback to notify the network additions
* to Connectivity Abstraction Layer.
* @param[in] errorCallback Callback to notify the network errors to
* Connectivity Abstraction Layer.
* @param[in] handle Threadpool Handle.
* @return #CA_STATUS_OK or Appropriate error code
*/
CAResult_t CAInitializeIP(CARegisterConnectivityCallback registerCallback,
......@@ -53,76 +54,77 @@ CAResult_t CAInitializeIP(CARegisterConnectivityCallback registerCallback,
CAErrorHandleCallback errorCallback, ca_thread_pool_t handle);
/**
* @brief Start IP Interface adapter.
* @return #CA_STATUS_OK or Appropriate error code
* Start IP Interface adapter.
* @return #CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAStartIP();
/**
* @brief Start listening server for receiving multicast search requests
* Start listening server for receiving multicast search requests.
* Transport Specific Behavior:
* IP Starts Multicast Server on a particular interface and prefixed port number and
* as per OIC Specification.
* @return #CA_STATUS_OK or Appropriate error code
* IP Starts Multicast Server on a particular interface and prefixed port
* number and as per OIC Specification.
* @return #CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAStartIPListeningServer();
/**
* @brief Start discovery servers for receiving multicast advertisements
* Start discovery servers for receiving multicast advertisements.
* Transport Specific Behavior:
* IP Starts multicast server on a particular interface and prefixed port
* number as per OIC Specification
* @return #CA_STATUS_OK or Appropriate error code
* number as per OIC Specification.
* @return #CA_STATUS_OK or Appropriate error code.
*/
CAResult_t CAStartIPDiscoveryServer();
/**
* @brief Sends data to the endpoint using the adapter connectivity.
* @param endpoint [IN] Remote Endpoint information (like ipaddress , port, reference uri
* and transport type) to which the unicast data has to be sent.
* @param data [IN] Data which is required to be sent.
* @param dataLen [IN] Size of data to be sent.
* @return The number of bytes sent on the network. Return value equal to -1 indicates error.
* @remark dataLen must be > 0.
* Sends data to the endpoint using the adapter connectivity.
* @param[in] endpoint Remote Endpoint information (like ipaddress,
* port, reference uri and transport type) to
* which the unicast data has to be sent.
* @param[in] data Data which is required to be sent.
* @param[in] dataLen Size of data to be sent.
* @note dataLen must be > 0.
* @return The number of bytes sent on the network, or -1 upon error.
*/
int32_t CASendIPUnicastData(const CAEndpoint_t *endpoint, const void *data,
uint32_t dataLen);
/**
* @brief Send Multicast data to the endpoint using the IP connectivity.
* @param endpoint [IN] Remote Endpoint information (like ipaddress , port)
* @param data [IN] Data which is required to be sent.
* @param dataLen [IN] Size of data to be sent.
* @return The number of bytes sent on the network. Return value equal to -1 indicates error.
* @remark dataLen must be > 0.
* Send Multicast data to the endpoint using the IP connectivity.
* @param[in] endpoint Remote Endpoint information (like ipaddress,
* port)
* @param[in] data Data which is required to be sent.
* @param[in] dataLen Size of data to be sent.
* @note dataLen must be > 0.
* @return The number of bytes sent on the network, or -1 upon error.
*/
int32_t CASendIPMulticastData(const CAEndpoint_t *endpoint, const void *data, uint32_t dataLen);
/**