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 #ifdef RA_ADAPTER
  42
  43 /**
  44  * Callback for bound JID
  45  * @param[out]   jid           Boud Jabber Identifier.
  46  */
  47 typedef void (*CAJidBoundCallback)(char *jid);
  48
  49 /**
  50  * CA Remote Access information for XMPP Client
  51  *
  52  */
  53 typedef struct
  54 {
  55     char *hostName;     /**< XMPP server hostname */
  56     uint16_t port;      /**< XMPP server serivce port */
  57     char *xmppDomain;  /**< XMPP login domain */
  58     char *userName;     /**< login username */
  59     char *password;     /**< login password */
  60     char *resource;     /**< specific resource for login */
  61     char *userJid;     /**< specific JID for login */
  62     CAJidBoundCallback jidBoundCallback;  /**< callback when JID bound */
  63 } CARAInfo_t;
  64
  65 #endif //RA_ADAPTER
  66
  67 #ifdef TCP_ADAPTER
  68 /**
  69  * Callback function to pass the connection information from CA to RI.
  70  * @param[out]   object           remote device information.
  71  * @param[out]   isConnected      Whether keepalive message needs to be sent.
  72  * @param[out]   isClient         Host Mode of Operation.
  73  */
  74 typedef void (*CAKeepAliveConnectionCallback)(const CAEndpoint_t *object, bool isConnected,
  75                                               bool isClient);
  76
  77 /**
  78  * Register connection status changes callback to process KeepAlive.
  79  * connection informations are delivered these callbacks.
  80  * @param[in]   ConnHandler     Connection status changes callback.
  81  */
  82 void CARegisterKeepAliveHandler(CAKeepAliveConnectionCallback ConnHandler);
  83 #endif
  84 /**
  85  * Initialize the connectivity abstraction module.
  86  * It will initialize adapters, thread pool and other modules based on the platform
  87  * compilation options.
  88  * @param[in]   transportType  transport type to initialize.
  89  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
  90  */
  91 CAResult_t CAInitialize(CATransportAdapter_t transportType);
  92
  93 /**
  94  * Terminate the connectivity abstraction module.
  95  * All threads, data structures are destroyed for next initializations.
  96  */
  97 void CATerminate();
  98
  99 /**
 100  * Starts listening servers.
 101  * This API is used by resource hosting server for listening multicast requests.
 102  * Based on the adapters configurations, different kinds of servers are started.
 103  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
 104  */
 105 CAResult_t CAStartListeningServer();
 106
 107 /**
 108  * Stops the server from receiving the multicast traffic. This is used by sleeping
 109  * device to not receives the multicast traffic.
 110  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
 111  */
 112 CAResult_t CAStopListeningServer();
 113
 114 /**
 115  * Starts discovery servers.
 116  * This API is used by resource required clients for listening multicast requests.
 117  * Based on the adapters configurations, different kinds of servers are started.
 118  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED
 119  */
 120 CAResult_t CAStartDiscoveryServer();
 121
 122 /**
 123  * Register request callbacks and response callbacks.
 124  *          Requests and responses are delivered these callbacks.
 125  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
 126  * @param[in]   RespHandler   Response Handler Callback.
 127  * @param[in]   ErrorHandler  Error Handler Callback.
 128  * @see     CARequestCallback
 129  * @see     CAResponseCallback
 130  * @see     CAErrorCallback
 131  */
 132 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
 133                        CAErrorCallback ErrorHandler);
 134
 135 /**
 136  * Create an endpoint description.
 137  * @param[in]   flags                 how the adapter should be used.
 138  * @param[in]   adapter               which adapter to use.
 139  * @param[in]   addr                  string representation of address.
 140  * @param[in]   port                  port (for IP_ADAPTER).
 141  * @param[out]  object                Endpoint which contains the above.
 142  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_INVALID_PARAM
 143  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
 144  * @see     CADestroyEndpoint
 145  */
 146 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
 147                             CATransportAdapter_t adapter,
 148                             const char *addr,
 149                             uint16_t port,
 150                             CAEndpoint_t **object);
 151
 152 /**
 153  * Destroy the remote endpoint created.
 154  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
 155  */
 156 void CADestroyEndpoint(CAEndpoint_t *object);
 157
 158 /**
 159  * Generating the token for matching the request and response.
 160  * @param[out]  token            Token for the request.
 161  * @param[in]   tokenLength      length of the token.
 162  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
 163  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_INVALID_PARAM
 164  * @remark  Token memory is destroyed by the caller using CADestroyToken().
 165  * @see     CADestroyToken
 166  */
 167 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
 168
 169 /**
 170  * Destroy the token generated by CAGenerateToken.
 171  * @param[in]   token    token to be freed.
 172  */
 173 void CADestroyToken(CAToken_t token);
 174
 175 /**
 176  * Send control Request on a resource.
 177  * @param[in]   object       Endpoint where the payload need to be sent.
 178  *                           This endpoint is delivered with Request or response callback.
 179  * @param[in]   requestInfo  Information for the request.
 180  * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
 181            ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
 182  */
 183 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
 184
 185 /**
 186  * Send the response.
 187  * @param[in]   object           Endpoint where the payload need to be sent.
 188  *                               This endpoint is delivered with Request or response callback.
 189  * @param[in]   responseInfo     Information for the response.
 190  * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
 191            ::CA_SEND_FAILED or ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
 192  */
 193 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
 194
 195 /**
 196  * Select network to use.
 197  * @param[in]   interestedNetwork    Connectivity Type enum.
 198  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
 199  *          ::CA_NOT_SUPPORTED or ::CA_ADAPTER_NOT_ENABLED or ::CA_MEMORY_ALLOC_FAILED
 200  */
 201 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
 202
 203 /**
 204  * Select network to unuse.
 205  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
 206  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED or
 207             ::CA_STATUS_NOT_INITIALIZED
 208  */
 209 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
 210
 211 /**
 212  * Get network information.
 213  * It should be destroyed by the caller as it Get Information.
 214  * @param[out]   info     LocalConnectivity objects
 215  * @param[out]   size     No Of Array objects
 216  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_STATUS_NOT_INITIALIZED or
 217  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
 218  */
 219 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
 220
 221 /**
 222  * To Handle the Request or Response.
 223  * @return   ::CA_STATUS_OK or ::CA_STATUS_NOT_INITIALIZED
 224  */
 225 CAResult_t CAHandleRequestResponse();
 226
 227 #ifdef RA_ADAPTER
 228 /**
 229  * Set Remote Access information for XMPP Client.
 230  * @param[in]   caraInfo          remote access info.
 231  *
 232  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
 233  */
 234 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
 235 #endif
 236
 237 #ifdef WITH_CHPROXY
 238 /**
 239  * This function sets uri being used for proxy.
 240  *
 241  * @param uri            NULL terminated resource uri for CoAP-HTTP Proxy.
 242  *
 243  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
 244  */
 245 CAResult_t CASetProxyUri(const char *uri);
 246 #endif
 247
 248 #ifdef __cplusplus
 249 } /* extern "C" */
 250 #endif
 251
 252 #endif /* CA_INTERFACE_H_ */
 253