Use `URI` all caps in documentation
[iotivity.git] / service / notification / cpp-wrapper / provider / inc / NSProviderService.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 C++ Wrapper APIs of Notification Service for Provider.\r
25  */\r
26 \r
27 #ifndef _NS_PROVIDER_SERVICE_H_\r
28 #define _NS_PROVIDER_SERVICE_H_\r
29 \r
30 #include <string>\r
31 #include "NSConsumer.h"\r
32 #include "NSSyncInfo.h"\r
33 #include "NSMessage.h"\r
34 #include "NSUtils.h"\r
35 #include "NSTopicsList.h"\r
36 \r
37 namespace OIC\r
38 {\r
39     namespace Service\r
40     {\r
41         class NSAcceptedConsumers;\r
42         /**\r
43          * @class   NSProviderService\r
44          * @brief   This class provides a set of C++APIs for Notification Provider.\r
45          */\r
46         class NSProviderService\r
47         {\r
48             public:\r
49                 /**\r
50                       * Provider uses this callback function to receive subscription request of consumer\r
51                       * @param[in] consumer  Consumer who subscribes the notification message resource\r
52                       */\r
53                 typedef void (*ConsumerSubscribedCallback)(std::shared_ptr<NSConsumer> );\r
54 \r
55                 /**\r
56                       * Provider use this callback function to receive the status of the message\r
57                       * synchronization\r
58                       * @param[in] sync Synchronization information of the notification message\r
59                       */\r
60                 typedef void (*MessageSynchronizedCallback)(NSSyncInfo );\r
61 \r
62 \r
63                 /**\r
64                       * @struct   ProviderConfig\r
65                       * @brief Provider sets this following configuration for registering callbacks and configs\r
66                       *  Set the subControllability, for notification servcie refering to following\r
67                       *  if subControllability, is true, provider decides to allow or deny for all the subscribing consumers.\r
68                       *  Otherwise(subControllability, is false) consumer decides to request subscription to discovered providers.\r
69                       */\r
70                 typedef struct\r
71                 {\r
72                     /** m_subscribeRequestCb - ConsumerSubscribedCallback callback listener.*/\r
73                     ConsumerSubscribedCallback m_subscribeRequestCb;\r
74                     /** m_syncInfoCb - MessageSynchronizedCallback callback listener.*/\r
75                     MessageSynchronizedCallback m_syncInfoCb;\r
76 \r
77                     /** subControllability - for setting the subscription controllability for Consumer */\r
78                     bool subControllability;\r
79                     /** userInfo - user defined information such as device friendly name */\r
80                     std::string userInfo;\r
81                     /* Set on/off for secure resource channel setting */\r
82                     bool resourceSecurity;\r
83                 } ProviderConfig;\r
84 \r
85                 /**\r
86                       * API for starting the NS Provider\r
87                       *\r
88                       * @return NSProviderService Pointer to singleton instance created\r
89                       */\r
90                 static NSProviderService *getInstance();\r
91 \r
92                 /**\r
93                       * Initialize notification service for provider\r
94                       * @param[in]  config   ProviderConfig Callback function pointers to onConsumerSubscribed,\r
95                       * and onMessageSynchronized function listeners\r
96                       * @return :: result code of Provider Service\r
97                       */\r
98                 NSResult start(ProviderConfig config);\r
99 \r
100                 /**\r
101                       * Terminate notification service for provider\r
102                       * @return :: result code of Provider Service\r
103                       */\r
104                 NSResult stop();\r
105 \r
106                 /**\r
107                       * Request to publish resource to cloud server\r
108                       * @param[in]  serverAddress combined with IP address and port number using delimiter :\r
109                       * @return  result code of Provider Service\r
110                       */\r
111                 NSResult enableRemoteService(const std::string &serverAddress);\r
112 \r
113                 /**\r
114                       * Request to cancel remote service using cloud server\r
115                       * @param[in]  serverAddress combined with IP address and port number using delimiter :\r
116                       * @return  result code of Provider Service\r
117                       */\r
118                 NSResult disableRemoteService(const std::string &serverAddress);\r
119 \r
120                 /**\r
121                       * Request to subscribe to remote MQ address as parameter.\r
122                       * @param[in] serverAddress server address combined with IP address and port number and MQ broker URI using delimiter :\r
123                       * @param[in] topicName the interest Topic name for subscription.\r
124                       * @return ::NS_OK or result code of NSResult\r
125                       */\r
126                 NSResult subscribeMQService(const std::string &serverAddress, const std::string &topicName);\r
127 \r
128                 /**\r
129                       * Send notification message to all subscribers\r
130                       * @param[in]  msg  Notification message including id, title, contentText\r
131                       * @return :: result code of Provider Service\r
132                       */\r
133                 NSResult sendMessage(const NSMessage &msg);\r
134 \r
135 \r
136                 /**\r
137                       * Send read-check to provider in order to synchronize notification status with other consumers\r
138                       * @param[in]  messageId  ID of Notification message to synchronize the status\r
139                       * @param[in]  type  NotificationSyncType of the SyncInfo message\r
140                       * @return :: OK or result code of NSResult\r
141                       */\r
142                 NSResult sendSyncInfo(uint64_t messageId, NSSyncInfo::NSSyncType type);\r
143 \r
144                 /**\r
145                      * Initialize NSMessage class, This function is valid only when subControllability is set true.\r
146                      * @return NSMessage *\r
147                      */\r
148                 NSMessage createMessage();\r
149 \r
150                 /**\r
151                      * Add topic to topic list which is located in provider service storage\r
152                      * @param[in]  topicName Topic name to add\r
153                      * @return :: OK or result code of NSResult\r
154                      */\r
155                 NSResult registerTopic(const std::string &topicName);\r
156 \r
157                 /**\r
158                      * Delete topic from topic list\r
159                      * @param[in]  topicName Topic name to delete\r
160                      * @return :: OK or result code of NSResult\r
161                      */\r
162                 NSResult unregisterTopic(const std::string &topicName);\r
163 \r
164                 /**\r
165                      * Request topics list already registered by provider user\r
166                      * @return :: Topic list\r
167                      */\r
168                 std::shared_ptr<NSTopicsList> getRegisteredTopicList();\r
169 \r
170                 /**\r
171                       *  get Provider config values\r
172                       * @return ProviderConfig callbaks set\r
173                       */\r
174                 ProviderConfig getProviderConfig();\r
175 \r
176                 /**\r
177                       *  request to get NSConsumer pointer\r
178                       * @param id -id as string\r
179                       *\r
180                       * @return shared pointer to NSConsumer\r
181                       */\r
182                 std::shared_ptr<NSConsumer> getConsumer(const std::string &id);\r
183 \r
184                 /**\r
185                       *  get handle of Consumers accepted.\r
186                       * @return m_acceptedConsumers -accepted Consumers\r
187                       */\r
188                 NSAcceptedConsumers *getAcceptedConsumers();\r
189 \r
190             private :\r
191                 ProviderConfig m_config;\r
192                 NSAcceptedConsumers *m_acceptedConsumers;\r
193 \r
194             private:\r
195                 NSProviderService();\r
196                 ~NSProviderService();\r
197                 NSProviderService(const NSProviderService &) = delete;\r
198                 NSProviderService &operator=(const NSProviderService &) = delete;\r
199                 NSProviderService(const NSProviderService &&) = delete;\r
200                 NSProviderService &operator=(const NSProviderService && ) = delete;\r
201 \r
202                 ::NSMessage *getNSMessage(const NSMessage &msg);\r
203                 static void onConsumerSubscribedCallback(::NSConsumer *consumer);\r
204                 static void onMessageSynchronizedCallback(::NSSyncInfo *syncInfo);\r
205         };\r
206     }\r
207 }\r
208 #endif /* _NS_PROVIDER_SERVICE_H_ */\r