X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=resource%2Fcsdk%2Fconnectivity%2Fapi%2Fcainterface.h;h=d82b67be0adefb4867248dc0a6462118ecd8e705;hb=17c68b2fd1e74586f85e552eeab4e32dc121f8a0;hp=27b4ff2ebd38ba33d61fa8e0aed16729e34f031e;hpb=8c01dff2c5bc5496f7dc1632c498943ec6ecb015;p=platform%2Fupstream%2Fiotivity.git diff --git a/resource/csdk/connectivity/api/cainterface.h b/resource/csdk/connectivity/api/cainterface.h index 27b4ff2..d82b67b 100644 --- a/resource/csdk/connectivity/api/cainterface.h +++ b/resource/csdk/connectivity/api/cainterface.h @@ -31,10 +31,7 @@ * Connectivity Abstraction Interface APIs. */ #include "cacommon.h" - -#ifdef __WITH_DTLS__ -#include "ocsecurityconfig.h" -#endif +#include "casecurityinterface.h" #ifdef __cplusplus extern "C" @@ -42,117 +39,87 @@ extern "C" #endif /** - * @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 function type for request delivery. + * @param[out] object Endpoint object from which the request is received. + * It contains endpoint address based on the connectivity type. + * @param[out] requestInfo Info for resource model to understand about the request. */ typedef void (*CARequestCallback)(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo); /** - * @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 + * Callback function type for response delivery. + * @param[out] object Endpoint object from which the response is received. + * @param[out] responseInfo Identifier which needs to be mapped with response. */ typedef void (*CAResponseCallback)(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo); /** - * @brief Callback function type for error - * @param object [OUT] remote device information - * @param errorInfo [OUT] CA Error information - * @return NONE + * Callback function type for error. + * @param[out] object remote device information. + * @param[out] errorInfo CA Error information. */ typedef void (*CAErrorCallback)(const CAEndpoint_t *object, const CAErrorInfo_t *errorInfo); -#ifdef __WITH_DTLS__ - -/** - * Binary blob containing device identity and the credentials for all devices - * trusted by this device. - */ -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; - /** - * @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 - */ -typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo); -#endif //__WITH_DTLS__ - -/** - * @brief Initialize the connectivity abstraction module. - * It will initialize adapters, thread pool and other modules based on the platform - * compilation options. + * 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 + * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED */ CAResult_t CAInitialize(); /** - * @brief Terminate the connectivity abstraction module. - * All threads, data structures are destroyed for next initializations. - * @return NONE + * Terminate the connectivity abstraction module. + * All threads, data structures are destroyed for next initializations. */ void CATerminate(); /** - * @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 + * 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 */ CAResult_t CAStartListeningServer(); /** - * @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 + * 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 + */ +CAResult_t CAStopListeningServer(); + +/** + * 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 */ CAResult_t CAStartDiscoveryServer(); /** - * @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. * @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[in] endpoint Endpoint which contains the above. + * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED * @remark The created Remote endpoint can be freed using CADestroyEndpoint(). * @see CADestroyEndpoint */ @@ -163,176 +130,88 @@ 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[in] 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_NOT_INITIALIZED * @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 ::CA_STATUS_FAILED ::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_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_NOT_SUPPORTED or + * ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED */ 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 */ 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 + * 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_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 + * To Handle the Request or Response. + * @return ::CA_STATUS_OK */ CAResult_t CAHandleRequestResponse(); #ifdef RA_ADAPTER /** - * @brief Set Remote Access information for XMPP Client. - * @param caraInfo [IN] remote access info. + * Set Remote Access information for XMPP Client. + * @param[in] caraInfo remote access info. * - * @return #CA_STATUS_OK + * @return ::CA_STATUS_OK */ CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo); #endif -#ifdef __WITH_DTLS__ - -/** - * Select the cipher suite for dtls handshake - * - * @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 - */ -CAResult_t CASelectCipherSuite(const uint16_t cipher); - -/** - * 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. - */ -CAResult_t CAEnableAnonECDHCipherSuite(const bool enable); - - -/** - * 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)') - * - * @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 - */ -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); - -/** - * Initiate DTLS handshake with selected cipher suite - * - * @param[IN] endpoint information of network address - * - * @retval CA_STATUS_OK Successful - * @retval CA_STATUS_FAILED Operation failed - */ -CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint); - -/** - * Close the DTLS session - * - * @param[IN] endpoint information of network address - * - * @retval CA_STATUS_OK Successful - * @retval CA_STATUS_FAILED Operation failed - */ -CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint); - -#endif /* __WITH_DTLS__ */ #ifdef __cplusplus } /* extern "C" */