service/notification/include/NSProviderInterface.h

   1 //******************************************************************\r
   2 //\r
   3 // Copyright 2016 Samsung Electronics All Rights Reserved.\r
   4 //\r
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\r
   6 //\r
   7 // Licensed under the Apache License, Version 2.0 (the "License");\r
   8 // you may not use this file except in compliance with the License.\r
   9 // You may obtain a copy of the License at\r
  10 //\r
  11 //      http://www.apache.org/licenses/LICENSE-2.0\r
  12 //\r
  13 // Unless required by applicable law or agreed to in writing, software\r
  14 // distributed under the License is distributed on an "AS IS" BASIS,\r
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  16 // See the License for the specific language governing permissions and\r
  17 // limitations under the License.\r
  18 //\r
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\r
  20 \r
  21 /**\r
  22  * @file\r
  23  *\r
  24  * This file provides APIs of Notification Service for Provider.\r
  25  */\r
  26 \r
  27 #ifndef _NS_PROVIDER_INTERFACE_H_\r
  28 #define _NS_PROVIDER_INTERFACE_H_\r
  29 \r
  30 #ifdef __cplusplus\r
  31 extern "C"\r
  32 {\r
  33 #endif // __cplusplus\r
  34 \r
  35 #include "NSCommon.h"\r
  36 #include <stdbool.h>\r
  37 #include <stdint.h>\r
  38 /**\r
  39  * Invoked when provider receives the subscription request of consumer.\r
  40  * @param[in] consumer  Consumer who subscribes the notification message resource\r
  41  */\r
  42 typedef void (*NSSubscribeRequestCallback)(NSConsumer *);\r
  43 \r
  44 /**\r
  45  * Invoked when synchronization data which has notification message\r
  46  * read/deleted event from consumer is received.\r
  47  * @param[in] sync  Synchronization information of the notification message\r
  48  */\r
  49 typedef void (*NSProviderSyncInfoCallback)(NSSyncInfo *);\r
  50 \r
  51 /**\r
  52  *  Set provider service with the following configuration\r
  53  */\r
  54 typedef struct\r
  55 {\r
  56     /* Invoked when the subscription request from consumer is received */\r
  57     NSSubscribeRequestCallback subRequestCallback;\r
  58     /* Invoked when the synchronization data, read and deleted, is sent by consumer is received */\r
  59     NSProviderSyncInfoCallback syncInfoCallback;\r
  60     /* Set the policy for notification servcie which checks whether provider is capable of \r
  61      * denying the subscription of notification message from consumer\r
  62      * and getting controllabliity to set consumer topic list.\r
  63      * If true, provider is able to control subscription request and consumer topic list.\r
  64      * Otherwise(policy is false), consumer can do the same.\r
  65      */\r
  66     bool subControllability;\r
  67     /* User defined information such as device friendly name */\r
  68     char * userInfo;\r
  69     /* Set on/off for secure resource channel setting */\r
  70     bool resourceSecurity;\r
  71 \r
  72 } NSProviderConfig;\r
  73 \r
  74 /**\r
  75  * Initialize notification service for provider\r
  76  * @param[in]  config   Refer to NSProviderConfig\r
  77  * @return ::NS_OK if the action is requested succesfully\r
  78  */\r
  79 NSResult NSStartProvider(NSProviderConfig config);\r
  80 \r
  81 /**\r
  82  * Terminate notification service for provider\r
  83  * @return ::NS_OK if the action is requested succesfully\r
  84  */\r
  85 NSResult NSStopProvider();\r
  86 \r
  87 /**\r
  88  * Request to publish resource using remote relay server\r
  89  * @param[in]  server address combined with IP address and port number using delimiter :\r
  90  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  91  */\r
  92 NSResult NSProviderEnableRemoteService(char * serverAddress);\r
  93 \r
  94 /**\r
  95  * Request to terminate remote service from relay server\r
  96  * @param[in]  server address combined with IP address and port number using delimiter :\r
  97  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
  98  */\r
  99 NSResult NSProviderDisableRemoteService(char * serverAddress);\r
 100 \r
 101 #ifdef WITH_MQ\r
 102 /**\r
 103  * Request to subscribe to remote MQ address as parameter.\r
 104  * @param[in] server address combined with IP address and port number and MQ broker uri using delimiter :\r
 105  * @param[in] topicName the interest Topic name for subscription.\r
 106  * @return ::NS_OK or result code of NSResult\r
 107  */\r
 108 NSResult NSProviderSubscribeMQService(const char * serverAddress, const char * topicName);\r
 109 #endif\r
 110 \r
 111 /**\r
 112  * Send notification message to all subscribers\r
 113  * @param[in]  message  Notification message including id, title, contentText\r
 114  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
 115  */\r
 116 NSResult NSSendMessage(NSMessage * msg);\r
 117 \r
 118 /**\r
 119  * Send acceptance to consumer who subscribes the resource of notification message\r
 120  * This function is valid only when subControllability is set true.\r
 121  * @param[in]  consumer  Consumer who subscribes the resource\r
 122  * @param[in]  accepted  the result of acceptance; ALLOW or DENY\r
 123  * @return ::NS_OK if this function is requested succesfully\r
 124  * or NS_FAIL if subContollability is false.\r
 125  */\r
 126 NSResult NSAcceptSubscription(const char * consumerId, bool accepted);\r
 127 \r
 128 /**\r
 129  * Send synchronizad state of notificaion message to consumers\r
 130  * @param[in]  messageiId  ID of notification message\r
 131  * @param[in]  type  SyncType of the syncInfo message\r
 132  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
 133  */\r
 134 NSResult NSProviderSendSyncInfo(uint64_t messageId, NSSyncType type);\r
 135 \r
 136 /**\r
 137  * Initialize NSMessage struct.\r
 138  * Service sets mandatory fields which message id and provider(device) id are filled with.\r
 139  * @return ::NSMessage *\r
 140  */\r
 141 NSMessage * NSCreateMessage();\r
 142 \r
 143 /**\r
 144  * Add topic to topic list which is located in provider service storage\r
 145  * @param[in]  topicName Topic name to add\r
 146  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
 147  */\r
 148 NSResult NSProviderRegisterTopic(const char * topicName);\r
 149 \r
 150 /**\r
 151  * Delete topic from topic list\r
 152  * @param[in]  topicName Topic name to delete\r
 153  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if wrong parameter is set.\r
 154  */\r
 155 NSResult NSProviderUnregisterTopic(const char * topicName);\r
 156 \r
 157 /**\r
 158  * Select a topic name for a consumer\r
 159  * @param[in]  consumerId  consumer id for which the user on provider selects a topic\r
 160  * @param[in]  topicName Topic name to select\r
 161  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if subContollability is false\r
 162  */\r
 163 NSResult NSProviderSetConsumerTopic(const char * consumerId, const char * topicName);\r
 164 \r
 165 /**\r
 166  * Unselect a topic from the topic list for consumer\r
 167  * @param[in]  consumerId  consumer id for which the user on provider unselects a topic\r
 168  * @param[in]  topicName Topic name to unselect\r
 169  * @return ::NS_OK if the action is requested succesfully or NS_FAIL if subContollability is false\r
 170  */\r
 171 NSResult NSProviderUnsetConsumerTopic(const char * consumerId, const char * topicName);\r
 172 \r
 173 /**\r
 174  * Request topic list with selection state for the consumer\r
 175  * @param[in] consumerid  the id of consumer which topic list is subscribed for\r
 176  * @return :: Topic list\r
 177  */\r
 178 NSTopicLL * NSProviderGetConsumerTopics(const char * consumerId);\r
 179 \r
 180 /**\r
 181  * Request topics list already registered by provider user\r
 182  * @return :: Topic list\r
 183  */\r
 184 NSTopicLL * NSProviderGetTopics();\r
 185 \r
 186 #ifdef __cplusplus\r
 187 }\r
 188 #endif // __cplusplus\r
 189 \r
 190 #endif /* _NS_PROVIDER_INTERFACE_H_ */\r
 191 \r