files/include/SAPInterface.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * PROPRIETARY/CONFIDENTIAL
   5  *
   6  * This software is the confidential and proprietary information of SAMSUNG
   7  * ELECTRONICS ("Confidential Information"). You shall not disclose such
   8  * Confidential Information and shall use it only in accordance with the terms
   9  * of the license agreement you entered into with SAMSUNG ELECTRONICS. SAMSUNG
  10  * make no representations or warranties about the suitability of the software,
  11  * either express or implied, including but not limited to the implied
  12  * warranties of merchantability, fitness for a particular purpose, or
  13  * non-infringement. SAMSUNG shall not be liable for any damages suffered by
  14  * licensee as a result of using, modifying or distributing this software or
  15  * its derivatives.
  16  * licensee arising out of or related to this software.
  17  *
  18  */
  19 #ifndef _SAPINTERFACE_H_
  20 #define _SAPINTERFACE_H_
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /***************************************************************************//**
  27  @brief  The enum defines the event codes for the Incremental Update Notification .
  28  @param  PEER_UNAVAILABLE: Defines that the peer has been uninstalled or Deregistered
  29  @param  PEER_AVAILABLE: Defines that the peer is installed or registered
  30  ****************************************************************************/
  31 typedef enum PeerStatus{
  32         PEER_AGENT_UNAVAILABLE,   ///<  Defines that the peer has been uninstalled or Deregistered
  33         PEER_AGENT_AVAILABLE       ///< Defines that the peer is installed or registered
  34 }PeerStatus;
  35
  36 /***************************************************************************//**
  37  @brief  The enum defines the event codes for Broadcast Event from SAP.
  38  @param  DEVICE_ATTACH_EVENT : Device Attach Compeleted.
  39  ****************************************************************************/
  40 typedef enum BroadcastEvent
  41 {
  42         DEVICE_ATTACH_EVENT = 0
  43 }BroadcastEvent;
  44
  45
  46 enum device_status{
  47
  48         DEVICE_DETACHED = 0x00, /// device detached
  49         DEVICE_ATTACHED = 0x01  /// device attached
  50 };
  51 //3 TBD: One of the above should be finalised after complete review.
  52
  53
  54 /***************************************************************************//**
  55  @brief  The enum defines the SAP Service Agent roles for Providers and Consumers across Peer Devices.
  56  @param  SERVICE_AGENT_ROLE_PROVIDER: The SERVICE AGENT PROVIDER Role can be played by an application connecting to SAP in order to achieve the service objectives, like accept/reject a service connection from a SERVICE AGENT CONSUMER and send/receive data.
  57  @param  SERVICE_AGENT_ROLE_CONSUMER: The SERVICE AGENT CONSUMER Role can be played by an application connecting to SAP in order to achieve the service objectives, like request a service connection to a SERVICE AGENT PROVIDER and send/receive data.
  58  ****************************************************************************/
  59 typedef enum ServiceAgentRole {
  60
  61         SERVICE_AGENT_ROLE_PROVIDER = 0,
  62         SERVICE_AGENT_ROLE_CONSUMER = 1
  63 }ServiceAgentRole;
  64
  65
  66 /***************************************************************************//**
  67  @brief  The enum defines the result of Service Connection Creation
  68  @param  CONNECTION_SUCCESS: Service Connection is successful. App can continue to send Data using sendData()
  69  @param  CONNECTION_ALREADY_EXIST: Service Connection  already exists. Connection already exist use the same. If sendData fails again, create new connection
  70  @param  CONNECTION_FAILURE_DEVICE_UNREACHABLE: Device is not reachable. It is not connected or connection is lost. Need to wait for connection again to retry
  71  @param  CONNECTION_FAILURE_INVALID_PEERAGENT: The peer agent details (peer ID etc.) are invalid. Peer Agent is invalid, so do findPeerAgent() again and retry service connection
  72  @param  CONNECTION_FAILURE_NETWORK: Connection failed due to network error. Try again. If error keeps happening, wait for connection and then retry.
  73  @param  CONNECTION_FAILURE_PEERAGENT_NO_RESPONSE: The remote peer did not response to request. Since there is no response from peer, the other side might be down or service is not supported in the peer. App can retry later
  74  @param  CONNECTION_FAILURE_PEERAGENT_REJECTED: The remote peer rejected the service connection. Peer has rejected, App can retry again
  75  ****************************************************************************/
  76 typedef enum ServiceConnectionResponseCode {
  77
  78         CONNECTION_SUCCESS = 0, ///< Service Connection is successful. App can continue to send Data using sendData()
  79         CONNECTION_ALREADY_EXIST, ///< Service Connection  already exists. Connection already exist use the same. If sendData fails again, create new connection
  80         CONNECTION_FAILURE_DEVICE_UNREACHABLE, ///< Device is not reachable. It is not connected or connection is lost. Need to wait for connection again to retry
  81         CONNECTION_FAILURE_INVALID_PEERAGENT, ///< The peer agent details (peer ID etc.) are invalid. Peer Agent is invalid, so do findPeerAgent() again and retry service connection
  82         CONNECTION_FAILURE_NETWORK, ///< Connection failed due to network error. Try again. If error keeps happening, wait for connection and then retry.
  83         CONNECTION_FAILURE_PEERAGENT_NO_RESPONSE, ///< The remote peer did not response to request. Since there is no response from peer, the other side might be down or service is not supported in the peer. App can retry later
  84         CONNECTION_FAILURE_PEERAGENT_REJECTED ///< The remote peer rejected the service connection. Peer has rejected, App can retry again
  85 }ServiceConnectionResponseCode;
  86
  87
  88 /***************************************************************************//**
  89  @brief  The enum defines the status codes returned when findPeerAgent is attempted.
  90  @param  PEER_AGENT_FOUND: Peer agent found successfully. App can create service connection using createServiceConnection()
  91  @param  PEER_AGENT_DEVICE_NOT_CONNECTED: When findPeerAgent was called, remote device was not connected. Wait for connection before retrying again
  92  @param  PEER_AGENT_SERVICE_NOT_FOUND: ASP Id or service intended in findPeerAgent not found in remote device. Service not supported at other side. Chk valid Agent Id and retry again
  93  @param  PEER_AGENT_FIND_TIMEDOUT: Request timed out without any response from the peer device. Retry again, it will succeed if service comes up at other side
  94  @param  PEER_AGENT_FIND_END: Search for peer agent completed or some internal error. Recheck passed parameters and retry
  95  ****************************************************************************/
  96 typedef enum FindPeerAgentResponseCode {
  97
  98         PEER_AGENT_FOUND = 0, ///< Peer agent found successfully. App can create service connection using createServiceConnection()
  99         PEER_AGENT_DEVICE_NOT_CONNECTED, ///< When findPeerAgent was called, remote device was not connected. Wait for connection before retrying again
 100         PEER_AGENT_SERVICE_NOT_FOUND, ///< ASP Id or service intended in findPeerAgent not found in remote device. Service not supported at other side. Chk valid Agent Id and retry again
 101         PEER_AGENT_FIND_TIMEDOUT, ///< Request timed out without any response from the peer device. Retry again, it will succeed if service comes up at other side
 102         PEER_AGENT_FIND_END ///< Search for peer agent completed or some internal error. Recheck passed parameters and retry
 103 }FindPeerAgentResponseCode;
 104
 105 /***************************************************************************//**
 106  @brief  The enum defines the error codes that shall be sent with onError callback, called when error occurs in an already established service connection.
 107  @param  CONNECTION_LOST_PEER_DISCONNECTED : Connection loss due to Peer device disconnected. Based on App logic retry can be done with createServiceConnection()
 108  @param  CONNECTION_LOST_DEVICE_DETACHED : Connection loss due to Peer device lost. Wait for new connection again to retry
 109  @param  CONNECTION_LOST_UNKNOWN_REASON : Connection loss due to unknown reason. Mostly development error, app can retry
 110  @remarks Error during the establishment of service connection shall be conveyed as response of service connection. onError shall not be called.
 111  ****************************************************************************/
 112 typedef enum ServiceConnectionErrorCode {
 113
 114         CONNECTION_LOST_PEER_DISCONNECTED = 0, ///< Connection loss due to Peer device disconnected. Based on App logic retry can be done with createServiceConnection()
 115         CONNECTION_LOST_DEVICE_DETACHED, ///< Connection loss due to Peer device lost. Wait for new connection again to retry
 116         CONNECTION_LOST_UNKNOWN_REASON ///< Connection loss due to unknown reason. Mostly development error, app can retry
 117 }ServiceConnectionErrorCode;
 118
 119
 120 /***************************************************************************//**
 121  @brief  The enum defines the reponse codes that shall be sent with FDefOnRegisterServiceAgentConfirm callback.
 122  @param REGISTER_SUCCESS: registration is success
 123  @param  DUPLICATE_REGISTRATION : App calls registerServiceAgent with same ASP ID again
 124  @param  INVALID_ARGUMENTS : Invalid arguments, like ASP ID NULL etc. Apps should check the  input params & retry
 125  @param  INTERNAL_ERROR : Any other internal error. App can retry registration.
 126  @remarks Each app can register multiple ASP ID, but they should be different
 127  ****************************************************************************/
 128 typedef enum RegisterAgentResponseCode {
 129         REGISTER_SUCCESS = 0,
 130         DUPLICATE_REGISTRATION,
 131         INVALID_IN_ARGUMENTS,
 132         INTERNAL_SAP_ERROR
 133 }RegisterAgentResponseCode;
 134
 135
 136 /***************************************************************************//**
 137  @brief  The enum defines the status of data transfer operation
 138  @param  DATA_SUCCESS: Data is sent successfully. App can continue to sendData() again
 139  @param  INVALID_ARGUMENTS: Invalid arguments, like improper channel id etc. app need to recheck the passed param and retry
 140  @param  INVALID_SERVICE_CONNECTION: The service connection indicated by the service handle does not exists. So creater service createServiceConnection() and retry
 141  @param  NETWORK_FAILURE: Data transfer failed because of network error. Retry again
 142  @param  BUFFER_FULL: Send buffer full.On receiving this application should wait for FDefOnSpaceAvailable before sending further data.
 143  @param  SDK_ERROR: Any other internal sdk error. App should recheck the params passed and retry
 144  ****************************************************************************/
 145 typedef enum DataTransferResultCode {
 146
 147         DATA_SUCCESS = 0, ///< Data is sent successfully. App can continue to sendData() again
 148         INVALID_ARGUMENTS, ///< Invalid arguments, like improper channel id etc. app need to recheck the passed param and retry
 149         INVALID_SERVICE_CONNECTION, ///< The service connection indicated by the service handle does not exists. So creater service createServiceConnection() and retry
 150         NETWORK_FAILURE, ///< The service connection indicated by the service handle does not exists. So creater service createServiceConnection() and retry
 151         BUFFER_FULL, ///< Send buffer full.On receiving this application should wait for FDefOnSpaceAvailable before sending further data.
 152         SDK_ERROR ///< Any other internal sdk error. App should recheck the params passed and retry
 153 }DataTransferResultCode;
 154
 155
 156 /***************************************************************************//**
 157  @brief  The enum defines the various connectivity types
 158  @param  SAP_BT: BT connectivity
 159  @param  SAP_BLE: BLE connectivity
 160  @param  SAP_TCP: TCP connectivity
 161  @param  SAP_USB: USB connectivity
 162  ****************************************************************************/
 163 typedef enum ConnectivityType {
 164
 165         SAP_ALL =0, ///< All connectivity
 166         SAP_BT=4 , ///< BT connectivity
 167         SAP_BLE=8, ///< BLE connectivity
 168         SAP_TCP_IP=16, ///< TCP connectivity
 169         SAP_USB=32, ///< USB connectivity
 170         SAP_CONNECTIVITY_END = 0xFF ///< End of Connectivity
 171 }ConnectivityType;
 172
 173
 174 /***************************************************************************//**
 175  @brief  The enum defines the status codes that may be used to convey generic states as needed for SAP interaction.
 176  @param  RESULT_TIMEOUT: When a request has timeout.
 177  @param  RESULT_FAILURE: On failure of a request.
 178  @param  RESULT_SUCCESS: On successfull execution of the request.
 179  @param  RESULT_INPROGRESS: Progressive status of SAP to indicate reason for temporary failure.
 180  ****************************************************************************/
 181 typedef enum{
 182
 183     RESULT_TIMEOUT = -2,
 184     RESULT_FAILURE =-1,
 185     RESULT_SUCCESS =0,
 186     RESULT_INPROGRESS = 1
 187 }SAP_RESULT_VAL;
 188
 189
 190 /***************************************************************************//**
 191  @brief  The enum defines the various Payload types
 192  @param  SAP_NONE: None
 193  @param  SAP_BINARY: Binary Payload
 194  @param  SAP_JSON: JSON Payload
 195  @param  SAP_ALL_PAYLOAD: Other PayloadTypes
 196  ****************************************************************************/
 197 typedef enum PayloadType {
 198
 199         SAP_NONE = 0x00,
 200         SAP_BINARY = 0x01, //BINARY Payloadtype supported
 201         SAP_JSON = 0x02, //JSON PayloadType supported
 202         SAP_ALL_PAYLOAD = 0xFF // Any other payloadType
 203 }PayloadType;
 204
 205 typedef enum ErrorCode {
 206
 207         UNKNOWN_REASON = 0x00,///<Reason Unknown
 208         SAP_ERROR_IPC_DISCONNECTED = 0x01,
 209 }SAPErrorCode;
 210
 211
 212 /***************************************************************************//**
 213  @brief  The enum defines the Qos Priority value as required by service profile
 214  @param  PRIORITY_LOW: Low Channel priority
 215  @param  PRIORITY_MEDIUM: Medium Channel priority
 216  @param  PRIORITY_HIGH: High channel priority is generally not preferred
 217  ****************************************************************************/
 218 typedef enum Priority {
 219
 220         PRIORITY_LOW = 0X00, //Low priority
 221         PRIORITY_MEDIUM,         //Medium priority
 222         PRIORITY_HIGH            //High priority
 223 }SAPPriority;
 224
 225
 226 /*****************************************************************************
 227  @brief  The enum defines the QOS-Arrival data rate values
 228  @param  DATARATE_LOW: Low data rate
 229  @param  DATARATE_HIGH: High data rate
 230  ****************************************************************************/
 231 typedef enum DataRate {
 232
 233         DATARATE_LOW = 0X00, //Low data rate
 234         DATARATE_HIGH //High data rate
 235 }SAPDataRate;
 236
 237
 238 /*****************************************************************************
 239  @brief  The enum indicates the type of QoS support being requested
 240  @param  UNRESTRICTED_INORDER: Unrestricted SDU and In-Order Delivery
 241  @param  UNRESTRICTED_UNORDER: Unrestricted SDU and Unordered Delivery
 242  @param  RESTRICTED_INORDER: Restricted SDU and In-Order Delivery
 243  @param  RESTRICTED_UNORDER: Restricted SDU and Unordered Delivery
 244  @param  RELIABLITY_DISABLE: Retransmission disabled
 245  @param  RELIABILITY_ENABLE: Retransmission enabled
 246  ****************************************************************************/
 247 typedef enum QosType {
 248
 249         UNRESTRICTED_INORDER = 0X00, //Unrestricted SDU and In-Order Delivery
 250         UNRESTRICTED_UNORDER = 0X01, //Unrestricted SDU and Unordered Delivery
 251         RESTRICTED_INORDER = 0X02, //Restricted SDU and In-Order Delivery
 252         RESTRICTED_UNORDER = 0X03, //Restricted SDU and Unordered Delivery
 253         RELIABLITY_DISABLE = 0X04, //Retransmission disabled
 254         RELIABILITY_ENABLE = 0X05 //Retransmission enabled
 255 }SAPQosType;
 256
 257
 258 /*****************************************************************************
 259  @brief  The enum defines the limit of connections restricted to a serivce agent
 260  @param  SERVICE_LIMIT_ANY: No restrictions
 261  @param  SERVICE_LIMIT_ONE_ACCESSORY: Can connect to multiple profiles in one Accessory
 262  @param  SERVICE_LIMIT_ONE_PEERAGENT: Can connect to a single profile in multiple accessories
 263  ****************************************************************************/
 264 typedef enum ServiceLimit{
 265
 266         SERVICE_LIMIT_ANY = 0X00, //Default
 267         SERVICE_LIMIT_ONE_ACCESSORY, //Can connect to multiple profiles in one Accessory
 268         SERVICE_LIMIT_ONE_PEERAGENT //Can connect to a single profile in multiple accessories
 269 }SAPServiceLimit;
 270
 271
 272 /***************************************************************************//**
 273  @brief  The structure tagQoSObject stores the details of Qos parameters associated with a channel
 274  @param  ubType: indicates the type of QoS support being requested
 275  @param  ubPriority: defines the Qos Priority value as required by service profile
 276  @param  ubDataRate: defines the QOS-Arrival data rate values
 277  ****************************************************************************/
 278 typedef struct tagQoSObject{
 279
 280         SAPQosType ubType; //Type of Qos support
 281         SAPPriority ubPriority; //Priority of the messages on the new session
 282         SAPDataRate ubDataRate; //Rate at which data is sent
 283 }QoSObj;
 284
 285
 286 /***************************************************************************//**
 287  @brief  The structure  tagChannelDesc is used to store the details associated with a channel
 288  @param  wChannelID: channel identifier.
 289  @param  ubNoOfPayloadType: No of payload type as listed in payloadTypeList.
 290  @param  payloadTypeList: Payload type supported (0 for JSON, 1 for Binary).
 291  @param  Qos: Qos requested from App
 292  ****************************************************************************/
 293 typedef struct tagChannelDesc{
 294
 295         unsigned short int wChannelID;  ///< Channel identifier
 296         unsigned short int ubNoOfPayloadType; ///< No of payload type as listed in payloadTypeList.
 297         PayloadType payloadTypeList; ///< List of payload types supported (0 for JSON, 1 for Binary)
 298         QoSObj Qos; ///< QoS requested from App
 299 }ChannelDesc;
 300
 301
 302 /***************************************************************************//**
 303  @brief  The structure  tagServiceDesc is used to store the details associated with a specific service
 304  @param  pchASPID: ASP Identifier that uniquely represent a profile.
 305  @param  pchSPFName: Friendly name for the ASP ID.
 306  @param  wConnectionTypeMask: Connectivity types that application is interested to support upon as per ConnectivityType.
 307  @param  ubRole: specifies if the application shall be a consumer (1) or provider(0).The role should be opposite for the 2 peers for a profile
 308  @param  pChDescArray : List of channels associated in the Service description.
 309  @param  numChannels : number of channels listed in pChDescList.
 310  @param  ubServiceLimit : Restricting the service connection based on App need
 311  @param  uwSvcWaitTime : Timeout value for Service connection establishment
 312  ****************************************************************************/
 313 typedef struct tagServiceDesc{
 314
 315         char* pchASPID; ///< ASP Identifier that uniquely represent a profile.
 316         char* pchSPFName; ///< Friendly name for the ASP ID.
 317         int  wConnectionTypeMask; ///< Connectivity types that application is interested to support upon as per ConnectivityType.
 318         unsigned char ubRole; ///< specifies if the application shall be a consumer (1) or provider(0). The role should be opposite for the 2 peers for a profile
 319         ChannelDesc *pChDescArray; ///< Array of channels associated in the Service description.
 320         short int numChannels; ///< number of channels listed in pChDescList.
 321         SAPServiceLimit ubServiceLimit; ///< Restricting the service connection based on App need
 322         unsigned short int uwSvcWaitTime; ///< Timeout value for Service connection establishment in seconds
 323 }ServiceDesc;
 324
 325
 326 /***************************************************************************//**
 327  @brief  The structure  tagPeerAgent is used to store the Peer agent details associated with a service profile ID
 328  @param  udwPeerDeviceID: Peer device ID
 329  @param  udwPeerAgentId: Peer agent running the service
 330  @param  pchPeerDeviceName: Peer Device Name
 331  @param  pchMACAddress: MAC Address
 332  @param  pchALEName: ALE Name
 333  @param  pchASPID: ASP ID supported
 334  @param  pchProfileVersion: ASP version
 335  @param  uwSvcWaitTime : Timeout value for Service connection establishment
 336  ****************************************************************************/
 337 typedef struct tagPeerAgent {
 338
 339         unsigned int udwPeerDeviceID; ///< Peer device ID
 340         unsigned int udwPeerAgentId; ///< Peer agent running the service
 341         char *pchPeerDeviceName; ///< Peer Device Name
 342         char *pchMACAddress; ///< MAC Address
 343         char *pchALEName; ///< ALE Name
 344         char *pchASPID; ///< ASP ID supported
 345         char *pchProfileVersion; ///< ASP version
 346         unsigned short int uwSvcWaitTime; ///< Timeout value for Service connection establishment
 347 }PeerAgent;
 348
 349
 350 /**************************************************************************//**
 351   @brief To check the status of SAP connection
 352   @returns : Returns integer value for sap connected status (Connected:1, Disconnected:0, Error:-1)
 353 * ************************************************************************** */
 354 int isSapConnected(void);
 355
 356 /**************************************************************************//**
 357 @brief This function is called by the application to get the agent id assigned for its service profiles
 358 @param pchASPID [in] : Profile id of the service
 359 @param role [in]  : Role (provider/consumer)
 360 @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS if get agent id request initiated successfully
 361 @remarks registerNotifications() needs to be called prior to calling this API. It needs to be called from App context
 362                  The Agent Id will be returned to the application in the registerServiceAgentConfirm() callback
 363 * ************************************************************************** */
 364 SAP_RESULT_VAL getRegisteredServiceAgent(char* pchASPID, ServiceAgentRole role);
 365
 366 /**************************************************************************//**
 367 @brief This function is called by the application for initialization operations. This will register the service id and links with corresponding agent Id .Result of this operation will be informed using FDefOnRegisterServiceAgentConfirm() callback.
 368 @param pRegServiceRequest [in]   : Service Registration of the provider/consumer
 369 @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of successfully intiated registration or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 370 @remarks registerNotifications() needs to be called prior to calling this API. It needs to be called from App context
 371 * ************************************************************************** */
 372  SAP_RESULT_VAL registerServiceAgent(ServiceDesc *pRegServiceRequest);
 373
 374 /**************************************************************************//**
 375  @brief This callback function gets triggered after registration of service agent registerServiceAgent() is completed .
 376  @param wStatusCode [in]   : int shall be returned with RESULT_SUCCESS in case of success and appropriate error code in case of failure.
 377  @param uwLocalAgentId [in]: LocalAgentId is unique identifier of the application represented to the SAP framework locally. It needs to be used in API as needed.
 378 **************************************************************************** */
 379 typedef  void (*FDefOnRegisterServiceAgentConfirm) (int wStatusCode, unsigned int uwLocalAgentId);
 380
 381 /**************************************************************************//**
 382 @brief  This will de-register the service from the SAP framework. Result of this operation will be informed using FDefOnDeregisterServiceAgentConfirm() callback.
 383 @param uwLocalAgentId [in]: LocalAgentId is unique identifier of the application represented to the SAP framework locally, which was returned as part of FDefOnRegisterServiceAgentComplete.
 384 @returns  returns SAP_RESULT_VAL with RESULT_SUCCESS in case of successfully intiated deregistration or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 385 @remarks The API needs to be called from App context
 386 * ************************************************************************** */
 387  SAP_RESULT_VAL  deRegisterServiceAgent(unsigned int uwLocalAgentId);
 388
 389 /**************************************************************************//**
 390  @brief This is the callback function.This function gets triggerd after deregister profile deRegisterServiceAgent() is completed
 391  @param wStatusCode [in]   : SAP_RESULT_VAL shall be returned with RESULT_SUCCESS in case of success and appropriate error code in case of failure.
 392  @param uwLocalAgentId [in]: LocalAgentId is unique identifier of the application represented to the SAP framework locally. It needs to be used in API as needed.
 393  @returns  returns SAP_VOID.
 394 * ************************************************************************** */
 395 typedef  void (*FDefOnDeregisterServiceAgentConfirm) (int wStatusCode, unsigned int uwLocalAgentId);
 396
 397
 398 /**************************************************************************//**
 399  @brief  The function findPeerAgent fetches handle to the associated PeerAgent as per ones own ASP ID as specified in ServiceDesc. uwLocalAgentId shall be indicate the same.
 400  The user will get the handle to remote PeerAgent in callback FDefOnPeerAgent.
 401  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that was received when  FDefOnRegisterServiceAgentComplete callback was called.
 402  @returns  returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 403  @remarks The API needs to be called from App context
 404  ****************************************************************************/
 405 SAP_RESULT_VAL findPeerAgent(unsigned int  uwLocalAgentId);
 406
 407
 408 /**************************************************************************//**
 409  @brief This callback function gets triggered as a result of findPeerAgent() called by application.
 410  @param  pPeerAgent [in] : The handle to the PeerAgent that has been discovered on call of findPeerAgent.
 411  @param uwLocalAgentId [in]: LocalAgentId is unique identifier of the application represented to the SAP framework locally. Should be same as one received in FDefOnRegisterServiceAgentConfirm callback.
 412  @param wStatusCode[in] : Status code indicating success or failure on call of findPeerAgent as per the FindPeerAgentResponseCode ENUM.
 413  @returns : returns SAP_VOID.
 414 * ************************************************************************** */
 415 typedef  void (*FDefOnPeerAgent) (unsigned int uwLocalAgentId, PeerAgent* pPeerAgent, int  wStatusCode);
 416
 417
 418 /**************************************************************************//**
 419  @brief This callback function gets triggered when a matching Service Agent is registered in a connected peer.
 420  @param  pPeerAgent [in] : The handle to the PeerAgent that has a new service agent.
 421  @param uwLocalAgentId [in]: LocalAgentId is unique identifier of the application represented to the SAP framework locally. This should be same as one received in FDefOnRegisterServiceAgentConfirm callback.
 422  @returns : returns SAP_VOID.
 423  @remarks: Upon receiving the PEER_AGENT_AVAILABLE the App can initiate a service Connection , Upon receiving the PEER_AGENT UNAVAILABLE the App has to wait for the PEER_AVAILABLE.
 424 * ************************************************************************** */
 425 typedef  void (*FDefOnPeerAgentIndication) (unsigned int uwLocalAgentId, PeerAgent* pPeerAgent, PeerStatus peerStatus);
 426
 427
 428 /**************************************************************************//**
 429  @brief  The function createServiceConnection establishes service connection with specified peer agent.The service connection success/failure is indicated via callback FDefOnServiceConnectionConfirm().
 430  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that was received in  FDefOnRegisterServiceAgentComplete callback.
 431  @param pPeerAgent [in]:Peer Agent containing the Service Id, App Id and Device id received in FDefOnPeerAgent callback.
 432  @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 433  @remarks RESULT_SUCCESS indicates that request for service connection has been successfully initiated. The actual service connection creation success/failure is indicated in callback FDefOnServiceConnectionConfirm(). The API needs to be called from App context
 434 *************************************************************************** */
 435 SAP_RESULT_VAL createServiceConnection(unsigned int uwLocalAgentId, PeerAgent* pPeerAgent);
 436
 437
 438 /**************************************************************************//**
 439  @brief This callback function will get triggered when a new incoming service connection request is received from a remote peer.
 440  The application shall call the function acceptServiceConnection to accept or  rejectServiceConnection to reject the connection.
 441  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that conveys local identifier of the Agent for which which service connection indication was received.
 442  @param uwServiceHandle [in]   : The handle for the service connection indicated.
 443  @param pPeerAgent [in]:Peer Agent containing the Service Id, App Id and Device id.
 444  @returns Returns SAP_VOID.
 445 *************************************************************************** */
 446 typedef  void (*FDefOnServiceConnectionIndication) (unsigned int uwLocalAgentId, unsigned int uwServiceHandle, PeerAgent* pPeerAgent);
 447
 448
 449 /**************************************************************************//**
 450  @brief Accept an incoming service connection request. This is typically called from the registered callback FDefOnServiceConnectionIndication().
 451  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that may be used to convey the specific identifier of the localAgentId with which service connection request was received.
 452  @param uwServiceHandle [in]   : The handle for the incoming service connection request.
 453  @param pPeerAgent [in]:Peer Agent containing the Service Id, App Id and Device id
 454  @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 455  @remarks The API needs to be called from App context
 456 **************************************************************************** */
 457 SAP_RESULT_VAL acceptServiceConnection(unsigned int uwLocalAgentId, unsigned int uwServiceHandle, PeerAgent* pPeerAgent);
 458
 459
 460 /**************************************************************************//**
 461  @brief Reject an incoming service connection request. This is typically called from the registered callback FDefOnServiceConnectionIndication().
 462  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that may be used to convey the specific identifier of the localAgentId with which service connection request was received.
 463  @param uwServiceHandle [in]   : The handle for the incoming service connection request.
 464  @param pPeerAgent [in]:Peer Agent containing the Service Id, App Id and Device id
 465  @returns : Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success or appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 466  @remarks The API needs to be called from App context
 467 * ************************************************************************** */
 468
 469 SAP_RESULT_VAL rejectServiceConnection(unsigned int uwLocalAgentId, unsigned int uwServiceHandle, PeerAgent* pPeerAgent);
 470
 471
 472 /**************************************************************************//**
 473  @brief This callback function gets triggerd to notify the success or failure of service connection request initiated by the application. Will be sent only to the initiator of the connection.
 474  @param uwLocalAgentId [in]: LocalAgentId is unique identifier that may be used to convey the specific identifier of the localAgentId with which service connection was established.
 475  @param uwServiceHandle [in]   : The handle for the service connection.
 476  @param pPeerAgent [in]:Peer Agent containing the Service Id, App Id and Device id
 477  @param wResponseCode [in]: status code:  Status code value is one of the ServiceConnectionResponseCode enum.
 478  @returns Returns SAP_VOID.
 479 * ************************************************************************** */
 480 typedef void (*FDefOnServiceConnectionConfirm) (unsigned int uwLocalAgentId, unsigned int uwServiceHandle,  PeerAgent* pPeerAgent, int wResponseCode);
 481
 482
 483 /**************************************************************************//**
 484  @brief Send data over a service connection. If send fails with BUFFER_FULL app should wait for FDefOnSpaceAvailable() callback
 485  @param uwServiceHandle [in]   : The handle for the service connection.
 486  @param ubChannelId [in] : The channel id on which data has to be sent
 487  @param uwPayloadLength [in]  : The length of payload data..
 488  @param pvBuffer [in]: The data buffer to be sent
 489  @returns  Returns one of the status codes in DataTransferResultCode ENUM.
 490  @remarks Max 65528 bytes can be sent . sendData should not be called in SAP callback and sendData should not be called simulataneous from different threads.
 491 * ************************************************************************** */
 492 DataTransferResultCode sendData(unsigned int uwServiceHandle, unsigned short int ubChannelId, unsigned int uwPayloadLength,void *pvBuffer);
 493
 494
 495 /**************************************************************************//**
 496  @brief Send Secure data over a service connection. If send fails with BUFFER_FULL app should wait for FDefOnSpaceAvailable() callback
 497  @param uwServiceHandle [in]   : The handle for the service connection.
 498  @param ubChannelId [in] : The channel id on which data has to be sent
 499  @param uwPayloadLength [in]  : The length of payload data..
 500  @param pvBuffer [in]: The data buffer to be sent
 501  @returns  Returns one of the status codes in DataTransferResultCode ENUM.
 502  @remarks Max 65528 bytes can be sent . sendSecureData should not be called in SAP callback and sendSecureData should not be called simulataneous from different threads.
 503 * ************************************************************************** */
 504 DataTransferResultCode sendSecureData(unsigned int uwServiceHandle, unsigned short int ubChannelId, unsigned int uwPayloadLength,void *pvBuffer);
 505
 506
 507 /**************************************************************************//**
 508  @brief This callback function gets triggered when the application receives data from an active service connection.
 509  @param uwServiceHandle [in]   : The handle for the service connection on which data has been received.
 510  @param  ubChannelId [in] : The channel id on which data has been received
 511  @param uwPayloadLength [in]  : The length of payload data.
 512  @param pvBuffer [in]: The data buffer that has been received
 513  @returns Returns SAP_VOID.
 514 * ************************************************************************** */
 515 typedef  void (*FDefOnReceive) (unsigned int uwServiceHandle, unsigned short int uwChannelId, unsigned int uwPayloadLength, void *pvBuffer);
 516
 517
 518 /**************************************************************************//**
 519 @brief  Terminate service connection corresponding to given service handle.
 520 @param uwServiceHandle [in] : The handle of the service Connection. The same handle returned in FDefOnServiceConnectionConfirm() should be used.
 521 @returns Returns RESULT_SUCCESS if successfully intitated the request else appropriate failure error code as specified in SAP_RESULT_VAL ENUM.
 522 @remarks RESULT_SUCCESS indicates that request for terminate service connection has been succesfully processed. The Api needs to be called in App context
 523 * ************************************************************************** */
 524 SAP_RESULT_VAL terminateServiceConnection(unsigned int uwServiceHandle);
 525
 526
 527 /**************************************************************************//**
 528  @brief This callback function will get triggered when a service connection is terminated as a result of a trigger from remote peer.
 529  @param uwServiceHandle [in]   : The handle for the service connection.
 530  @returns : returns SAP_VOID.
 531 * ************************************************************************* */
 532 typedef void (*FDefOnServiceTerminationIndication) (unsigned int uwServiceHandle,int wStatusCode);
 533
 534
 535 /**************************************************************************//**
 536  @brief This callback function gets triggered when error occurs but was not relayed as part of a request-response transaction. Triggered also if the other side has called terminateServiceConnection()
 537  @param uwServiceHandle [in]   : The handle for the service connection on which data has been received.
 538  @param dwErrorCode [in]   : Error Code defined in SAPErrorCode Enum
 539  @returns Returns SAP_VOID.
 540 * ************************************************************************** */
 541 typedef  void (*FDefOnError) (unsigned int uwServiceHandle, unsigned int dwErrorCode);
 542
 543
 544 /**************************************************************************//**
 545  @brief This callback function gets triggerd when space is avilable for application to write. Application should wait for this callback if send returns failure with BUFFER_FULL
 546  @param uwServiceHandle [in]   : The handle for the service connection on which data has been received.
 547  @param uwChannelId [in] : The channel identifier on which the onSpaceAvailable callback is called.
 548  @param  ulSpaceAvailable [in] : How much space is available in bytes
 549  @returns Returns DataTransferResultCode.
 550 * ************************************************************************** */
 551 typedef  void (*FDefOnSpaceAvailable) (unsigned int uwServiceHandle, unsigned short int uwChannelId, unsigned int ulSpaceAvailable);
 552
 553 /***************************************************************************//**
 554  @brief  The structure  holds references to callback for application for various events from framework.
 555  @param  pfnOnRegisterServiceAgentConfirm: Register Service Agent Confirmation function pointer
 556  @param  pfnOnDataIndication: Data Indication function pointer
 557  @param  FDefOnServiceConnectionIndication: Service connection indication function pointer
 558  @param  pfnOnServiceTerminationIndication: Service termination indication function pointer
 559  @param  pfnOnServiceCreateConfirm: Service create confirm function pointer
 560  @param  pfnOnPeerAgent: Peer Agent availability function pointer
 561  @param  pfnOnSpaceAvailable: Space available for send function pointer
 562  @param  pfnOnError: Error function pointer
 563  @param  pfnOnDeRegisterServiceAgentConfirm: DeRegister service Agent function pointer
 564  ****************************************************************************/
 565 typedef  void (*FDefOnDeviceStatus) (ConnectivityType device_type, enum device_status status);
 566
 567 typedef struct tagSAPNotification
 568 {
 569         FDefOnRegisterServiceAgentConfirm pfnOnRegisterServiceAgentConfirm; ///< Register Service Agent Confirmation function pointer
 570         FDefOnReceive pfnOnDataIndication; ///< Data Indication function pointer
 571         FDefOnServiceConnectionIndication pfnOnServiceConnectionIndication; ///< Service connection indication function pointer
 572         FDefOnServiceTerminationIndication pfnOnServiceTerminationIndication; ///< Service termination indication function pointer
 573         FDefOnServiceConnectionConfirm pfnOnServiceCreateConfirm; ///< Service create confirm function pointer
 574         FDefOnPeerAgent pfnOnPeerAgent; ///< Peer Agent availability function pointer
 575         FDefOnSpaceAvailable pfnOnSpaceAvailable; ///< Space available for send function pointer
 576         FDefOnError  pfnOnError; ///< Error function pointer
 577         FDefOnDeregisterServiceAgentConfirm pfnOnDeRegisterServiceAgentConfirm; ///< DeRegister service Agent function pointer
 578         FDefOnDeviceStatus pfnDeviceStatus;
 579         FDefOnPeerAgentIndication pfnOnPeerAgentNoti; ///<  Peer Agent Notification
 580 }SAPNotification;
 581
 582
 583  /**************************************************************************//**
 584 @brief This function registers all the callbacks in SAPNotification. This needs to be the first API that needs to be called from the App.
 585 @param notiFuncs [in]   : Notification functions which are to be registered for getting callback.
 586 @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success and appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 587 * ************************************************************************** */
 588 SAP_RESULT_VAL registerNotifications(SAPNotification notiFuncs);
 589
 590
 591 /**************************************************************************//**
 592 @brief This function deregisters all the callbacks in SAPNotification. This should be called when App get FDefOnError callback.
 593 @returns Returns SAP_RESULT_VAL with RESULT_SUCCESS in case of success and appropriate failure error if any error as per the SAP_RESULT_VAL ENUM.
 594 * ************************************************************************** */
 595 SAP_RESULT_VAL deregisterNotifications(void);
 596
 597 #ifdef __cplusplus
 598 }
 599 #endif
 600
 601 #endif /*_SAPINTERFACE_H_ */