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 /**\r
  40  * Provider uses this callback function to receive subscription request of consumer\r
  41  * @param[in] consumer        Consumer who subscribes the resource\r
  42  */\r
  43 typedef void (*NSSubscribeRequestCallback)(NSConsumer *);\r
  44 \r
  45 /**\r
  46  * Provider use this callback function to receive the status of the message\r
  47  * synchronization\r
  48  * @param[in] sync        Synchronization information of the notification message\r
  49  */\r
  50 typedef void (*NSProviderSyncInfoCallback)(NSSyncInfo *);\r
  51 \r
  52 /**\r
  53  *  Set provider service with the following configuration\r
  54  */\r
  55 typedef struct\r
  56 {\r
  57     /* Invoked when the subscription request from consumer is received */\r
  58     NSSubscribeRequestCallback subRequestCallback;\r
  59     /* Invoked when the synchronization data, read and deleted, is sent by consumer is received */\r
  60     NSProviderSyncInfoCallback syncInfoCallback;\r
  61     /* Set the policy for notification servcie refering to following\r
  62      * if policy is true, provider decides to allow or deny for all the subscribing consumers.\r
  63      * Otherwise(policy is false) consumer decides to request subscription to discovered providers.\r
  64      */\r
  65     bool policy;\r
  66     /* User Information */\r
  67     char * userInfo;\r
  68 \r
  69 } NSProviderConfig;\r
  70 \r
  71 /**\r
  72  * Initialize notification service for provider service\r
  73  * @param[in]  config   Refer to NSProviderConfig\r
  74  * @return ::NS_OK or result code of NSResult\r
  75  */\r
  76 NSResult NSStartProvider(NSProviderConfig config);\r
  77 \r
  78 /**\r
  79  * Terminate notification service for provider\r
  80  * @return ::NS_OK or result code of NSResult\r
  81  */\r
  82 NSResult NSStopProvider();\r
  83 \r
  84 /**\r
  85  * Request to publish resource to cloud server\r
  86  * @param[in]  server address combined with IP address and port number using delimiter :\r
  87  * @return ::NS_OK or result code of NSResult\r
  88  */\r
  89 NSResult NSProviderEnableRemoteService(char *serverAddress);\r
  90 \r
  91 /**\r
  92  * Request to cancel remote service using cloud server\r
  93  * @param[in]  server address combined with IP address and port number using delimiter :\r
  94  * @return ::NS_OK or result code of NSResult\r
  95  */\r
  96 NSResult NSProviderDisableRemoteService(char *serverAddress);\r
  97 \r
  98 /**\r
  99  * Send notification message to all subscribers\r
 100  * @param[in]  message  Notification message including id, title, contentText\r
 101  * @return ::NS_OK or result code of NSResult\r
 102  */\r
 103 NSResult NSSendMessage(NSMessage *msg);\r
 104 \r
 105 /**\r
 106  * Send acceptance to consumer who subscribes the resource of notification message\r
 107  * @param[in]  consumer  Consumer who subscribes the resource\r
 108  * @param[in]  accepted  the result of acceptance; Allow or Deny\r
 109  * @return ::NS_OK or result code of NSResult\r
 110  */\r
 111 NSResult NSAcceptSubscription(NSConsumer *consumer, bool accepted);\r
 112 \r
 113 /**\r
 114  * Get consumer list that is stored in the cache of notification service\r
 115  * @param[in]  list  Consumer list\r
 116  * @param[in]  size  the number of consumers stored in the cache\r
 117  * @return ::NS_OK or result code of NSResult\r
 118  */\r
 119 //TODO will use Function.\r
 120 // NSResult NSGetConsumerList(uint8_t *list, uint32_t size);\r
 121 \r
 122 /**\r
 123  * Send read-check to provider in order to synchronize notification status with other consumers\r
 124  * @param[in]  message  Notification message to synchronize the status\r
 125  * @return ::NS_OK or result code of NSResult\r
 126  */\r
 127 NSResult NSProviderSendSyncInfo(uint64_t messageId, NSSyncType type);\r
 128 \r
 129 /**\r
 130  * Initialize NSMessage struct, our service set message id and provider(device) id\r
 131  * @return ::NSMessage *\r
 132  */\r
 133 NSMessage * NSCreateMessage();\r
 134 \r
 135 /**\r
 136  * Create empty topic list which is required to set by following APIs\r
 137  * @return ::NSTopicList\r
 138  */\r
 139 NSTopicList * NSProviderCreateTopicList();\r
 140 \r
 141 /**\r
 142  * Add topic to topic list which is able to be created\r
 143  * by NSProviderCreateTopicList function\r
 144  * @param[out]  topicList  Topic list added with topic name\r
 145  * @param[in]  topicName Topic name to add\r
 146  * @return ::NS_OK or result code of NSResult\r
 147  */\r
 148 NSResult NSProviderAddTopic(NSTopicList** topicList, char* topicName);\r
 149 \r
 150 /**\r
 151  * Delete topic from topic list\r
 152  * @param[out]  topicList  Topic list deleted with topic name\r
 153  * @param[in]  topicName Topic name to delete\r
 154  * @return ::NS_OK or result code of NSResult\r
 155  */\r
 156 NSResult NSProviderDeleteTopic(NSTopicList** topicList, char* topicName);\r
 157 \r
 158 /**\r
 159  * Select a topic for consumer\r
 160  * @param[out]  topicList  Topic list with selected and unselected topics for consumer\r
 161  * @param[in]  consumerId  consumer id for which the user on provider selects a topic\r
 162  * @param[in]  topicName Topic name to select\r
 163  * @return ::NS_OK or result code of NSResult\r
 164  */\r
 165 NSResult NSProviderSelectTopic(NSTopicList** topicList, char* consumerId, char* topicName);\r
 166 \r
 167 /**\r
 168  * Unselect a topic from the topic list for consumer\r
 169  * @param[out]  topicList  Topic list with selected and unselected topics for consumer\r
 170  * @param[in]  consumerId  consumer id for which the user on provider unselects a topic\r
 171  * @param[in]  topicName Topic name to unselect\r
 172  * @return ::NS_OK or result code of NSResult\r
 173  */\r
 174 NSResult NSProviderUnselectTopic(NSTopicList** topicList, char* consumerId, char* topicName);\r
 175 \r
 176 /**\r
 177  * Request all the topics which has already registered by user\r
 178  * @param[in] consumerid  the id of consumer which subscribes topics\r
 179  * if NULL, all the registered topic list is returned\r
 180  * @return :: list of NSTopic\r
 181  */\r
 182 NSTopicList * NSProviderGetTopics(char *consumerId);\r
 183 \r
 184 /**\r
 185  * Request to register topics to provide to consumers\r
 186  * @param[in]  topicList  List of NSTopic\r
 187  * the consumerId of NSTopicList struct shoud be set NULL\r
 188  * @return ::NS_OK or result code of NSResult\r
 189  */\r
 190 NSResult NSProviderRegisterTopics(NSTopicList *topicList);\r
 191 \r
 192 /**\r
 193  * Set recommended topics for a consumer\r
 194  * @param[in]  topicList  List of NSTopic recommended by provider\r
 195  * the consumerId of NSTopicList struct should be set consumerId\r
 196  * @return ::NS_OK or result code of NSResult\r
 197  */\r
 198 NSResult NSProviderRecommendTopics(char* consumerId, NSTopicList *topicList);\r
 199 \r
 200 #ifdef __cplusplus\r
 201 }\r
 202 #endif // __cplusplus\r
 203 \r
 204 #endif /* _NS_PROVIDER_INTERFACE_H_ */\r
 205 \r