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