resource/csdk/connectivity/api/cainterface.h

   1 /* ****************************************************************
   2  *
   3  * Copyright 2014 Samsung Electronics All Rights Reserved.
   4  *
   5  *
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  ******************************************************************/
  20
  21 /**
  22  * @file
  23  *
  24  * This file contains the APIs for Resource Model to use.
  25  */
  26
  27 #ifndef CA_INTERFACE_H_
  28 #define CA_INTERFACE_H_
  29
  30 /**
  31  * Connectivity Abstraction Interface APIs.
  32  */
  33 #include "cacommon.h"
  34 #include "casecurityinterface.h"
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #endif
  40
  41 /**
  42  * Callback function type for request delivery.
  43  * @param[out]   object       Endpoint object from which the request is received.
  44  *                            It contains endpoint address based on the connectivity type.
  45  * @param[out]   requestInfo  Info for resource model to understand about the request.
  46  */
  47 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
  48                                   const CARequestInfo_t *requestInfo);
  49
  50 /**
  51  * Callback function type for response delivery.
  52  * @param[out]   object           Endpoint object from which the response is received.
  53  * @param[out]   responseInfo     Identifier which needs to be mapped with response.
  54  */
  55 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
  56                                    const CAResponseInfo_t *responseInfo);
  57 /**
  58  * Callback function type for error.
  59  * @param[out]   object           remote device information.
  60  * @param[out]   errorInfo        CA Error information.
  61  */
  62 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
  63                                 const CAErrorInfo_t *errorInfo);
  64
  65 /**
  66  * Initialize the connectivity abstraction module.
  67  * It will initialize adapters, thread pool and other modules based on the platform
  68  * compilation options.
  69  *
  70  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
  71  */
  72 CAResult_t CAInitialize();
  73
  74 /**
  75  * Terminate the connectivity abstraction module.
  76  * All threads, data structures are destroyed for next initializations.
  77  */
  78 void CATerminate();
  79
  80 /**
  81  * Starts listening servers.
  82  * This API is used by resource hosting server for listening multicast requests.
  83  * Based on the adapters configurations, different kinds of servers are started.
  84  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
  85  */
  86 CAResult_t CAStartListeningServer();
  87
  88 /**
  89  * Stops the server from receiving the multicast traffic. This is used by sleeping
  90  * device to not receives the multicast traffic.
  91  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
  92  */
  93 CAResult_t CAStopListeningServer();
  94
  95 /**
  96  * Starts discovery servers.
  97  * This API is used by resource required clients for listening multicast requests.
  98  * Based on the adapters configurations, different kinds of servers are started.
  99  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
 100  */
 101 CAResult_t CAStartDiscoveryServer();
 102
 103 /**
 104  * Register request callbacks and response callbacks.
 105  *          Requests and responses are delivered these callbacks.
 106  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
 107  * @param[in]   RespHandler   Response Handler Callback.
 108  * @see     CARequestCallback
 109  * @see     CAResponseCallback
 110  * @see     CAErrorCallback
 111  */
 112 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
 113                        CAErrorCallback ErrorHandler);
 114
 115 /**
 116  * Create an endpoint description.
 117  * @param[in]   flags                 how the adapter should be used.
 118  * @param[in]   adapter               which adapter to use.
 119  * @param[in]   addr                  string representation of address.
 120  * @param[in]   port                  port (for IP_ADAPTER).
 121  * @param[in]   endpoint              Endpoint which contains the above.
 122  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
 123  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
 124  * @see     CADestroyEndpoint
 125  */
 126 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
 127                             CATransportAdapter_t adapter,
 128                             const char *addr,
 129                             uint16_t port,
 130                             CAEndpoint_t **object);
 131
 132 /**
 133  * Destroy the remote endpoint created.
 134  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
 135  */
 136 void CADestroyEndpoint(CAEndpoint_t *object);
 137
 138 /**
 139  * Generating the token for matching the request and response.
 140  * @param[in]   token            Token for the request.
 141  * @param[in]   tokenLength      length of the token.
 142  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
 143  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
 144  * @remark  Token memory is destroyed by the caller using CADestroyToken().
 145  * @see     CADestroyToken
 146  */
 147 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
 148
 149 /**
 150  * Destroy the token generated by CAGenerateToken.
 151  * @param[in]   token    token to be freed.
 152  */
 153 void CADestroyToken(CAToken_t token);
 154
 155 /**
 156  * Send control Request on a resource.
 157  * @param[in]   object       Endpoint where the payload need to be sent.
 158  *                           This endpoint is delivered with Request or response callback.
 159  * @param[in]   requestInfo  Information for the request.
 160  * @return  ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
 161  */
 162 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
 163
 164 /**
 165  * Send the response.
 166  * @param[in]   object           Endpoint where the payload need to be sent.
 167  *                               This endpoint is delivered with Request or response callback.
 168  * @param[in]   responseInfo     Information for the response.
 169  * @return  ::CA_STATUS_OK or  ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
 170  */
 171 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
 172
 173 /**
 174  * Select network to use.
 175  * @param[in]   interestedNetwork    Connectivity Type enum.
 176  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
 177  *          ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
 178  */
 179 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
 180
 181 /**
 182  * Select network to unuse.
 183  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
 184  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
 185  */
 186 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
 187
 188 /**
 189  * Get network information.
 190  * It should be destroyed by the caller as it Get Information.
 191  * @param[out]   info     LocalConnectivity objects
 192  * @param[out]   size     No Of Array objects
 193  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
 194  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
 195  */
 196 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
 197
 198 /**
 199  * To Handle the Request or Response.
 200  * @return   ::CA_STATUS_OK
 201  */
 202 CAResult_t CAHandleRequestResponse();
 203
 204 #ifdef RA_ADAPTER
 205 /**
 206  * Set Remote Access information for XMPP Client.
 207  * @param[in]   caraInfo          remote access info.
 208  *
 209  * @return  ::CA_STATUS_OK
 210  */
 211 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
 212 #endif
 213
 214
 215
 216 #ifdef __cplusplus
 217 } /* extern "C" */
 218 #endif
 219
 220 #endif /* CA_INTERFACE_H_ */
 221