resource-container: Install unit tests
[iotivity.git] / resource / csdk / stack / include / internal / occlientcb.h
1 /* ****************************************************************
2  *
3  * Copyright 2014 Intel Mobile Communications GmbH 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 contains the definition and types for client's callback mode and functions.
25  */
26
27
28 #ifndef OC_CLIENT_CB_H_
29 #define OC_CLIENT_CB_H_
30
31 #include "ocstack.h"
32 #include "ocresource.h"
33 #include "cacommon.h"
34
35
36 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41
42 #ifdef WITH_PRESENCE
43 /**
44  * Data structure For presence Discovery.
45  * This is the TTL associated with presence.
46  */
47 typedef struct OCPresence
48 {
49     /** Time to Live. */
50     uint32_t TTL;
51
52     /** Time out. */
53     uint32_t * timeOut;
54
55     /** TTL Level. */
56     uint32_t TTLlevel;
57 } OCPresence;
58 #endif // WITH_PRESENCE
59
60 /**
61  * Forward declaration of resource type.
62  */
63 typedef struct resourcetype_t OCResourceType;
64
65 /**
66  * Data structure for holding client's callback context, methods and Time to Live,
67  * connectivity Types, presence and resource type, request uri etc.
68  */
69 typedef struct ClientCB {
70     /** callback method defined in application address space. */
71     OCClientResponseHandler callBack;
72
73     /** callback context data. */
74     void * context;
75
76     /** callback method to delete context data. */
77     OCClientContextDeleter deleteCallback;
78
79     /** Qos for the request */
80     CAMessageType_t type;
81
82     /**  when a response is recvd with this token, above callback will be invoked. */
83     CAToken_t token;
84
85     /** a response is recvd with this token length.*/
86     uint8_t tokenLength;
87
88     CAHeaderOption_t *options;
89
90     uint8_t numOptions;
91
92     CAPayload_t payload;
93
94     size_t payloadSize;
95
96     CAPayloadFormat_t payloadFormat;
97
98     /** Invocation handle tied to original call to OCDoResource().*/
99     OCDoHandle handle;
100
101     /** This is used to determine if all responses should be consumed or not.
102      * (For now, only pertains to OC_REST_OBSERVE_ALL vs. OC_REST_OBSERVE functionality).*/
103     OCMethod method;
104
105     /** This is the sequence identifier the server applies to the invocation tied to 'handle'.*/
106     uint32_t sequenceNumber;
107
108     /** The canonical form of the request uri associated with the call back.*/
109     char * requestUri;
110
111     /** Remote address complete.*/
112     OCDevAddr * devAddr;
113
114 #ifdef WITH_PRESENCE
115     /** Struct to hold TTL info for presence.*/
116     OCPresence * presence;
117
118     /** Struct to hold a resource type name for filtering a presence interesting.*/
119     OCResourceType * interestingPresenceResourceType;
120 #endif
121
122     /** The connectivity type on which the request was sent on.*/
123     OCConnectivityType conType;
124
125     /** The TTL for this callback. Holds the time till when this callback can
126      * still be used. TTL is set to 0 when the callback is for presence and observe.
127      * Presence has ttl mechanism in the "presence" member of this struct and observes
128      * can be explicitly cancelled.*/
129     uint32_t TTL;
130
131     /** next node in this list.*/
132     struct ClientCB    *next;
133 } ClientCB;
134
135 //TODO: Now ocstack is directly accessing the clientCB list to process presence.
136 //      It should be avoided after we make a presence feature separately.
137 /**
138  * Linked list of ClientCB node.
139  */
140 extern struct ClientCB *g_cbList;
141
142 /**
143  * This method is used to add a client callback method in cbList.
144  *
145  * @param[out] clientCB            The resulting node from making this call. Null if out of memory.
146  * @param[in]  cbData              Address to client callback function.
147  * @param[in]  type                Qos type.
148  * @param[in]  token               Identifier for OTA CoAP comms.
149  * @param[in]  tokenLength         Length for OTA CoAP comms.
150  * @param[in]  options             The address of an array containing the vendor specific header
151  *                                 options to be sent with the request.
152  * @param[in]  numOptions          Number of header options to be included.
153  * @param[in]  payload             Request payload.
154  * @param[in]  payloadSize         Size of payload.
155  * @param[in]  payloadFormat       Format of payload.
156  * @param[in]  handle              masked in the public API as an 'invocation handle'
157  *                                 Used for callback management.
158  * @param[in]  method              A method via which this client callback is expected to operate
159  * @param[in]  devAddr             The Device address.
160  * @param[in]  requestUri          The resource uri of the request.
161  * @param[in]  resourceTypeName    The resource type associated with a presence request.
162  * @param[in]  ttl                 time to live in coap_ticks for the callback.
163  *
164  * @note If the handle you're looking for does not exist, the stack will reply with a RST message.
165  *
166  * @return OC_STACK_OK for Success, otherwise some error value.
167  */
168 OCStackResult AddClientCB(ClientCB** clientCB,
169                           OCCallbackData* cbData,
170                           CAMessageType_t type,
171                           CAToken_t token,
172                           uint8_t tokenLength,
173                           CAHeaderOption_t *options,
174                           uint8_t numOptions,
175                           CAPayload_t payload,
176                           size_t payloadSize,
177                           CAPayloadFormat_t payloadFormat,
178                           OCDoHandle *handle,
179                           OCMethod method,
180                           OCDevAddr *devAddr,
181                           char *requestUri,
182                           char *resourceTypeName,
183                           uint32_t ttl);
184
185 /**
186  * This method is used to remove a callback node from cbList.
187  *
188  * @param[in]  cbNode               Address to client callback node.
189  */
190 void DeleteClientCB(ClientCB *cbNode);
191
192 /**
193  * This method is used to clear the cbList.
194  */
195 void DeleteClientCBList(void);
196
197 /**
198  * This method is used to search and retrieve a cb node in cbList using token.
199  *
200  * @param[in]  token                Token to search for.
201  * @param[in]  tokenLength          The Length of the token.
202  *
203  * @return address of the node if found, otherwise NULL
204  */
205 ClientCB* GetClientCBUsingToken(const CAToken_t token,
206                                 const uint8_t tokenLength);
207
208 /**
209  * This method is used to search and retrieve a cb node in cbList using a handle.
210  *
211  * @param[in]  handle               Handle to search for.
212  *
213  * @return address of the node if found, otherwise NULL
214  */
215 ClientCB* GetClientCBUsingHandle(const OCDoHandle handle);
216
217 #ifdef WITH_PRESENCE
218 /**
219  * This method is used to search and retrieve a cb node in cbList using a uri.
220  *
221  * @param[in]  requestUri           Uri to search for.
222  *
223  * @return address of the node if found, otherwise NULL
224  */
225 ClientCB* GetClientCBUsingUri(const char *requestUri);
226 #endif // WITH_PRESENCE
227
228
229 #ifdef __cplusplus
230 } /* extern "C" */
231 #endif
232
233
234 #endif // OC_CLIENT_CB_H_
235