Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / api / cainterface.h
index 27b4ff2..1dd7039 100644 (file)
  * Connectivity Abstraction Interface APIs.
  */
 #include "cacommon.h"
-
-#ifdef __WITH_DTLS__
-#include "ocsecurityconfig.h"
-#endif
+#include "casecurityinterface.h"
 
 #ifdef __cplusplus
 extern "C"
 {
 #endif
 
+#ifdef RA_ADAPTER
+
 /**
- * @brief   Callback function type for request delivery.
- * @param   object      [OUT] Endpoint object from which the request is received. It contains
- *                            endpoint address based on the connectivity type.
- * @param   requestInfo [OUT] Info for resource model to understand about the request.
- * @return  NONE
+ * Callback for bound JID
+ * @param[out]   jid           Boud Jabber Identifier.
  */
-typedef void (*CARequestCallback)(const CAEndpoint_t *object,
-                                  const CARequestInfo_t *requestInfo);
+typedef void (*CAJidBoundCallback)(char *jid);
 
 /**
- * @brief   Callback function type for response delivery.
- * @param   object          [OUT] Endpoint object from which the response is received.
- * @param   responseInfo    [OUT] Identifier which needs to be mapped with response.
- * @return  NONE
+ * CA Remote Access information for XMPP Client
+ *
  */
-typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
-                                   const CAResponseInfo_t *responseInfo);
+typedef struct
+{
+    char *hostName;     /**< XMPP server hostname */
+    uint16_t port;      /**< XMPP server serivce port */
+    char *xmppDomain;  /**< XMPP login domain */
+    char *userName;     /**< login username */
+    char *password;     /**< login password */
+    char *resource;     /**< specific resource for login */
+    char *userJid;     /**< specific JID for login */
+    CAJidBoundCallback jidBoundCallback;  /**< callback when JID bound */
+} CARAInfo_t;
+
+#endif //RA_ADAPTER
+
+#ifdef TCP_ADAPTER
 /**
- * @brief   Callback function type for error
- * @param   object          [OUT] remote device information
- * @param   errorInfo       [OUT] CA Error information
- * @return  NONE
+ * Callback function to pass the connection information from CA to RI.
+ * @param[out]   object           remote device information.
+ * @param[out]   isConnected      Whether keepalive message needs to be sent.
+ * @param[out]   isClient         Host Mode of Operation.
  */
-typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
-                                const CAErrorInfo_t *errorInfo);
-
-#ifdef __WITH_DTLS__
+typedef void (*CAKeepAliveConnectionCallback)(const CAEndpoint_t *object, bool isConnected,
+                                              bool isClient);
 
 /**
- * Binary blob containing device identity and the credentials for all devices
- * trusted by this device.
+ * Register connection status changes callback to process KeepAlive.
+ * connection informations are delivered these callbacks.
+ * @param[in]   ConnHandler     Connection status changes callback.
  */
-typedef struct
-{
-   unsigned char identity[DTLS_PSK_ID_LEN]; /** identity of self */
-   uint32_t num;                            /** number of credentials in this blob */
-   OCDtlsPskCreds *creds;                   /** list of credentials. Size of this
-                                                array is determined by 'num' variable. */
-} CADtlsPskCredsBlob_t;
-
+void CARegisterKeepAliveHandler(CAKeepAliveConnectionCallback ConnHandler);
+#endif
 /**
- * @brief   Callback function type for getting DTLS credentials.
- * @param   credInfo          [OUT] DTLS credentials info. Handler has to allocate new memory for
- *                                  both credInfo and credInfo->creds which is then freed by CA
- * @return  NONE
+ * Initialize the connectivity abstraction module.
+ * It will initialize adapters, thread pool and other modules based on the platform
+ * compilation options.
+ * @param[in]   transportType  transport type to initialize.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
  */
-typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo);
-#endif //__WITH_DTLS__
+CAResult_t CAInitialize(CATransportAdapter_t transportType);
 
 /**
- * @brief   Initialize the connectivity abstraction module.
- *          It will initialize adapters, thread pool and other modules based on the platform
- *          compilation options.
- *
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED or #CA_MEMORY_ALLOC_FAILED
+ * Terminate the connectivity abstraction module.
+ * All threads, data structures are destroyed for next initializations.
  */
-CAResult_t CAInitialize();
+void CATerminate(void);
 
 /**
- * @brief   Terminate the connectivity abstraction module.
- *          All threads, data structures are destroyed for next initializations.
- * @return  NONE
+ * Starts listening servers.
+ * This API is used by resource hosting server for listening multicast requests.
+ * Based on the adapters configurations, different kinds of servers are started.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
  */
-void CATerminate();
+CAResult_t CAStartListeningServer(void);
 
 /**
- * @brief   Starts listening servers.
- *          This API is used by resource hosting server for listening multicast requests.
- *          Based on the adapters configurations, different kinds of servers are started.
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED
+ * Stops the server from receiving the multicast traffic. This is used by sleeping
+ * device to not receives the multicast traffic.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
  */
-CAResult_t CAStartListeningServer();
+CAResult_t CAStopListeningServer(void);
 
 /**
- * @brief   Starts discovery servers.
- *          This API is used by resource required clients for listening multicast requests.
- *          Based on the adapters configurations, different kinds of servers are started.
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED
+ * Starts discovery servers.
+ * This API is used by resource required clients for listening multicast requests.
+ * Based on the adapters configurations, different kinds of servers are started.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
  */
-CAResult_t CAStartDiscoveryServer();
+CAResult_t CAStartDiscoveryServer(void);
 
 /**
- * @brief   Register request callbacks and response callbacks.
- *          Requests and responses are delivered these callbacks .
- * @param   ReqHandler   [IN] Request callback ( for GET,PUT ..etc)
- * @param   RespHandler  [IN] Response Handler Callback
+ * Register request callbacks and response callbacks.
+ *          Requests and responses are delivered these callbacks.
+ * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
+ * @param[in]   RespHandler   Response Handler Callback.
+ * @param[in]   ErrorHandler  Error Handler Callback.
  * @see     CARequestCallback
  * @see     CAResponseCallback
  * @see     CAErrorCallback
- * @return  NONE
  */
 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
                        CAErrorCallback ErrorHandler);
 
-#ifdef __WITH_DTLS__
-/**
- * @brief   Register callback to get DTLS PSK credentials.
- * @param   GetDTLSCredentials   [IN] GetDTLS Credetials callback
- * @return  #CA_STATUS_OK
- */
-CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
-#endif //__WITH_DTLS__
-
 /**
- * @brief   Create an endpoint description
- * @param   flags               [IN]  how the adapter should be used
- * @param   adapter             [IN]  which adapter to use
- * @param   addr                [IN]  string representation of address
- * @param   port                [IN]  port (for IP_ADAPTER)
- * @param   endpoint            [OUT] Endpoint which contains the above
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED
+ * Create an endpoint description.
+ * @param[in]   flags                 how the adapter should be used.
+ * @param[in]   adapter               which adapter to use.
+ * @param[in]   addr                  string representation of address.
+ * @param[in]   port                  port (for IP_ADAPTER).
+ * @param[out]  object                Endpoint which contains the above.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_INVALID_PARAM
  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
  * @see     CADestroyEndpoint
  */
@@ -163,176 +150,117 @@ CAResult_t CACreateEndpoint(CATransportFlags_t flags,
                             CAEndpoint_t **object);
 
 /**
- * @brief   Destroy the remote endpoint created
- * @param   object  [IN] Remote Endpoint object created with CACreateEndpoint
- * @return  NONE
+ * Destroy the remote endpoint created.
+ * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
  */
 void CADestroyEndpoint(CAEndpoint_t *object);
 
 /**
- * @brief   Generating the token for matching the request and response.
- * @param   token          [OUT] Token for the request
- * @param   tokenLength    [IN]  length of the token
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED or #CA_MEMORY_ALLOC_FAILED
- *          or #CA_STATUS_NOT_INITIALIZED
+ * Generating the token for matching the request and response.
+ * @param[out]  token            Token for the request.
+ * @param[in]   tokenLength      length of the token.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
+ *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_INVALID_PARAM
  * @remark  Token memory is destroyed by the caller using CADestroyToken().
  * @see     CADestroyToken
  */
 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
 
 /**
- * @brief   Destroy the token generated by CAGenerateToken
- * @param   token   [IN] token to be freed
- * @return  NONE
+ * Destroy the token generated by CAGenerateToken.
+ * @param[in]   token    token to be freed.
  */
 void CADestroyToken(CAToken_t token);
 
 /**
- * @brief   Send control Request on a resource
- * @param   object      [IN] Endpoint where the payload need to be sent.
+ * Send control Request on a resource.
+ * @param[in]   object       Endpoint where the payload need to be sent.
  *                           This endpoint is delivered with Request or response callback.
- * @param   requestInfo [IN] Information for the request.
- * @return  #CA_STATUS_OK #CA_STATUS_FAILED #CA_MEMORY_ALLOC_FAILED
+ * @param[in]   requestInfo  Information for the request.
+ * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
+           ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
  */
 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
 
 /**
- * @brief   Send the response
- * @param   object          [IN] Endpoint where the payload need to be sent.
- *                               This endpoint is delivered with Request or response callback
- * @param   responseInfo    [IN] Information for the response
- * @return  #CA_STATUS_OK or  #CA_STATUS_FAILED or #CA_MEMORY_ALLOC_FAILED
- */
-CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
-
-/**
- * @brief   Send notification to the remote object
- * @param   object          [IN] Endpoint where the payload need to be sent.
+ * Send the response.
+ * @param[in]   object           Endpoint where the payload need to be sent.
  *                               This endpoint is delivered with Request or response callback.
- * @param   responseInfo    [IN] Information for the response.
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED or #CA_MEMORY_ALLOC_FAILED
+ * @param[in]   responseInfo     Information for the response.
+ * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
+           ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
  */
-CAResult_t CASendNotification(const CAEndpoint_t *object,
-                      const  CAResponseInfo_t *responseInfo);
+CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
 
 /**
- * @brief   Select network to use
- * @param   interestedNetwork   [IN] Connectivity Type enum
- * @return  #CA_STATUS_OK or #CA_NOT_SUPPORTED or #CA_STATUS_FAILED or #CA_NOT_SUPPORTED
+ * Select network to use.
+ * @param[in]   interestedNetwork    Connectivity Type enum.
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
+ *          ::CA_NOT_SUPPORTED or ::CA_ADAPTER_NOT_ENABLED or ::CA_MEMORY_ALLOC_FAILED
  */
 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
 
 /**
- * @brief   Select network to unuse
- * @param   nonInterestedNetwork    [IN] Connectivity Type enum
- * @return  #CA_STATUS_OK or #CA_NOT_SUPPORTED or #CA_STATUS_FAILED
+ * Select network to unuse.
+ * @param[in]   nonInterestedNetwork     Connectivity Type enum.
+ * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED or
+            ::CA_STATUS_NOT_INITIALIZED
  */
 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
 
 /**
- * @brief   Get network information
- *          It should be destroyed by the caller as it Get Information.
- * @param   info    [OUT] LocalConnectivity objects
- * @param   size    [OUT] No Of Array objects
- * @return  #CA_STATUS_OK or #CA_STATUS_FAILED or #CA_STATUS_INVALID_PARAM or
-*                #CA_MEMORY_ALLOC_FAILED
- */
-CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
-
-/**
- * @brief    To Handle the Request or Response
- * @return   #CA_STATUS_OK
+ * Get network information.
+ * It should be destroyed by the caller as it Get Information.
+ * @param[out]   info     LocalConnectivity objects
+ * @param[out]   size     No Of Array objects
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
+ *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
  */
-CAResult_t CAHandleRequestResponse();
-
-#ifdef RA_ADAPTER
-/**
- * @brief   Set Remote Access information for XMPP Client.
- * @param   caraInfo          [IN] remote access info.
- *
- * @return  #CA_STATUS_OK
- */
-CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
-#endif
-
-
-#ifdef __WITH_DTLS__
+CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, size_t *size);
 
 /**
- * Select the cipher suite for dtls handshake
+ * Get supported network adapter.
  *
- * @param[IN] cipher  cipher suite (Note : Make sure endianness)
- *                               0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
- *                               0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
- *                               0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
- *
- * @retval  CA_STATUS_OK    Successful
- * @retval  CA_STATUS_INVALID_PARAM  Invalid input argumets
- * @retval  CA_STATUS_FAILED Operation failed
+ * @return  Bit combinations of CATransportAdapter_t enumeration which indicate enabled adapter.
  */
-CAResult_t CASelectCipherSuite(const uint16_t cipher);
+CATransportAdapter_t CAGetSelectedNetwork(void);
 
 /**
- * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls
- *
- * @param[IN] enable  TRUE/FALSE enables/disables anonymous cipher suite
- *
- * @retval  CA_STATUS_OK    Successful
- * @retval  CA_STATUS_FAILED Operation failed
- *
- * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
+ * To Handle the Request or Response.
+ * @return   ::CA_STATUS_OK or ::CA_STATUS_NOT_INITIALIZED
  */
-CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
-
+CAResult_t CAHandleRequestResponse(void);
 
+#ifdef RA_ADAPTER
 /**
- * Generate ownerPSK using PRF
- * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
- *                                    'ID of new device(Resource Server)',
- *                                    'ID of owner smart-phone(Provisioning Server)')
+ * Set Remote Access information for XMPP Client.
+ * @param[in]   caraInfo          remote access info.
  *
- * @param[IN] endpoint  information of network address
- * @param[IN] label  Ownership transfer method e.g)"oic.sec.doxm.jw"
- * @param[IN] labelLen  Byte length of label
- * @param[IN] rsrcServerDeviceID  ID of new device(Resource Server)
- * @param[IN] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID
- * @param[IN] provServerDeviceID  label of previous owner
- * @param[IN] provServerDeviceIDLen  byte length of provServerDeviceID
- * @param[IN,OUT] ownerPSK  Output buffer for owner PSK
- * @param[IN] ownerPSKSize  Byte length of the ownerPSK to be generated
- *
- * @retval  CA_STATUS_OK    Successful
- * @retval  CA_STATUS_FAILED Operation failed
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
  */
-CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
-                              const uint8_t* label, const size_t labelLen,
-                              const uint8_t* rsrcServerDeviceID,
-                              const size_t rsrcServerDeviceIDLen,
-                              const uint8_t* provServerDeviceID,
-                              const size_t provServerDeviceIDLen,
-                              uint8_t* ownerPSK, const size_t ownerPSKSize);
+CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
+#endif
 
 /**
- * Initiate DTLS handshake with selected cipher suite
+ * This function sets URI being used for proxy.
  *
- * @param[IN] endpoint  information of network address
+ * @param uri            NULL terminated resource URI for CoAP-HTTP Proxy.
  *
- * @retval  CA_STATUS_OK    Successful
- * @retval  CA_STATUS_FAILED Operation failed
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
  */
-CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
+CAResult_t CASetProxyUri(const char *uri);
 
+#ifdef IP_ADAPTER
 /**
- * Close the DTLS session
+ * This function return zone id related from ifindex and address.
  *
- * @param[IN] endpoint  information of network address
+ * @param[in] ifindex     interface index.
+ * @param[out] zoneId     pointer of zoneId string.
  *
- * @retval  CA_STATUS_OK    Successful
- * @retval  CA_STATUS_FAILED Operation failed
+ * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
  */
-CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
-
-#endif /* __WITH_DTLS__ */
+CAResult_t CAGetLinkLocalZoneId(uint32_t ifindex, char **zoneId);
+#endif
 
 #ifdef __cplusplus
 } /* extern "C" */