Use `URI` all caps in documentation
[iotivity.git] / service / notification / include / NSConsumerInterface.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 Consumer.
25  */
26
27 #ifndef _NS_CONSUMER_INTERFACE_H_
28 #define _NS_CONSUMER_INTERFACE_H_
29
30 #ifdef __cplusplus
31 extern "C"
32 {
33 #endif // __cplusplus
34
35 #include "NSCommon.h"
36
37 /**
38  * Invoked when the provider state is changed
39  * @param[in] provider  Provider which has the notification resource
40  * @param[in] state  Response which has the provider state
41  */
42 typedef void (* NSProviderStateCallback)(NSProvider *, NSProviderState);
43
44 /**
45  * Invoked when the notification message from provider is received
46  * synchronization
47  * @param[in] message  Notification message
48  */
49 typedef void (* NSMessageReceivedCallback)(NSMessage *);
50
51 /**
52  * Invoked when the synchronization data which has notification message
53  * read/delete event from provider/consumer is received
54  * synchronization
55  * @param[in] syncInfo  Synchronization information of the notification message
56  */
57 typedef void (* NSSyncInfoReceivedCallback)(NSSyncInfo *);
58
59 typedef struct
60 {
61     NSProviderStateCallback changedCb;
62     NSMessageReceivedCallback messageCb;
63     NSSyncInfoReceivedCallback syncInfoCb;
64
65 } NSConsumerConfig;
66
67 /**
68  * Initialize notification service for consumer
69  * @param[in] config  NSConsumerconfig structure of callback functions
70  * @return ::NS_OK or result code of NSResult
71  */
72 NSResult NSStartConsumer(NSConsumerConfig config);
73
74 /**
75  * Terminate notification service for consumer
76  * @return ::NS_OK or result code of NSResult
77  */
78 NSResult NSStopConsumer(void);
79
80 /**
81  * Request to discover to remote address as parameter.
82  * @param[in] serverAddress combined with IP address and port number using delimiter :
83  * @return ::NS_OK or result code of NSResult
84  */
85 NSResult NSConsumerEnableRemoteService(const char * serverAddress);
86
87 #ifdef WITH_MQ
88 /**
89  * Request to subscribe to remote MQ address as parameter.
90  * @param[in] serverAddress server address combined with IP address and port number and MQ broker URI using delimiter :
91  * @param[in] topicName the interest MQ Topic name for subscription.
92  * @return ::NS_OK or result code of NSResult
93  */
94 NSResult NSConsumerSubscribeMQService(const char * serverAddress, const char * topicName);
95 #endif
96
97 /**
98  * Request discovery manually
99  * @return ::NS_OK or result code of NSResult
100  */
101 NSResult NSRescanProvider(void);
102
103 /**
104  * Request to subscribe notification message resource of provider
105  * @param[in] providerId the Id of Provider who send the notification message
106  * @return ::NS_OK or result code of NSResult
107  */
108 NSResult NSSubscribe(const char * providerId);
109
110 /**
111  * Request to unsubscribe in order not to receive notification message from provider
112  * @param[in]  providerId  the Id of Provider who send the notification message
113  * @return ::NS_OK or result code of NSResult
114  */
115 NSResult NSUnsubscribe(const char * providerId);
116
117 /**
118  * Send sync type to provider in order to synchronize notification status with other consumers
119  * when consumer consumes the notification such as READ, DELETE
120  * @param[in] providerId Provider id of the Notification message
121  * @param[in] messageId Notification message id to synchronize the status
122  * @param[in] type changed notification status from NSSyncType
123  * @return ::NS_OK or result code of NSResult
124  */
125 NSResult NSConsumerSendSyncInfo(
126         const char * providerId, uint64_t messageId, NSSyncType type);
127
128 /**
129  * Request NSProvider that is matched by provider id
130  * @param[in] providerId the id of provider that user wants to get
131  * @return NSProvider
132  */
133 NSProvider * NSConsumerGetProvider(const char * providerId);
134
135 /**
136  * Request NSTopic list that is subscribed from provider
137  * @param[in] providerId the Id of provider that user wants to get
138  * @return NSResult
139  */
140 NSTopicLL * NSConsumerGetTopicList(const char * providerId);
141
142 /**
143  * Select Topic list that is wanted to subscribe from provider
144  * @param[in] providerId the Id of provider that user wants to set
145  * @param[in] topics the topic list that user wants to set
146  * @return NSResult
147  */
148 NSResult NSConsumerUpdateTopicList(const char * providerId, NSTopicLL * topics);
149
150 #ifdef __cplusplus
151 }
152 #endif // __cplusplus
153
154 #endif // _NS_CONSUMER_INTERFACE_H_