1 //******************************************************************
3 // Copyright 2014 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
25 * This file contains the definition, types and interfaces for server request
29 #ifndef OC_SERVER_REQUEST_H
30 #define OC_SERVER_REQUEST_H
33 #include "cainterface.h"
36 * The signature of the internal call back functions to handle responses from entity handler
38 typedef OCStackResult (* OCEHResponseHandler)(OCEntityHandlerResponse * ehResponse);
41 * following structure will be created in occoap and passed up the stack on the server side.
43 typedef struct OCServerRequest
45 /** The REST method retrieved from received request PDU.*/
48 /** Accept format retrieved from the received request PDU. */
49 OCPayloadFormat acceptFormat;
51 /** resourceUrl will be filled in occoap using the path options in received request PDU.*/
52 char resourceUrl[MAX_URI_LENGTH];
54 /** resource query send by client.*/
55 char query[MAX_QUERY_LENGTH];
57 /** qos is indicating if the request is CON or NON.*/
58 OCQualityOfService qos;
60 /** Observe option field.*/
61 uint32_t observationOption;
63 /** Observe Result field.*/
64 OCStackResult observeResult;
66 /** number of Responses.*/
69 /** Response Entity Handler .*/
70 OCEHResponseHandler ehResponseHandler;
72 /** Remote endpoint address **/
75 /** The ID of server request*/
78 /** Token for the request.*/
79 CAToken_t requestToken;
81 /** token length the request.*/
84 /** The ID of CoAP pdu (Kept in CoAp).*/
87 /** For Delayed Response.*/
88 uint8_t delayedResNeeded;
90 /** Number of vendor specific header options.*/
91 uint8_t numRcvdVendorSpecificHeaderOptions;
93 /** An Array of received vendor specific header options.*/
94 OCHeaderOption rcvdVendorSpecificHeaderOptions[MAX_HEADER_OPTIONS];
96 /** Request to complete.*/
97 uint8_t requestComplete;
99 /** Linked list; for multiple server request.*/
100 struct OCServerRequest * next;
102 /** Flag indicating slow response.*/
105 /** Flag indicating notification.*/
106 uint8_t notificationFlag;
111 /** payload is retrieved from the payload of the received request PDU.*/
114 // WARNING: Do NOT add attributes after payload as they get overwritten
115 // when payload content gets copied over!
120 * Following structure will be created in ocstack to aggregate responses
121 * (in future: for block transfer).
123 typedef struct OCServerResponse {
125 /** Linked list; for multiple server response.*/
126 struct OCServerResponse * next;
128 /** this is the pointer to server payload data to be transferred.*/
131 /** Remaining size of the payload data to be transferred.*/
132 uint16_t remainingPayloadSize;
134 /** Requests to handle.*/
135 OCRequestHandle requestHandle;
139 * Handler function for sending a response from a single resource
141 * @param ehResponse Pointer to the response from the resource.
146 OCStackResult HandleSingleResponse(OCEntityHandlerResponse * ehResponse);
149 * Handler function for sending a response from multiple resources, such as a collection.
150 * Aggregates responses from multiple resource until all responses are received then sends the
151 * concatenated response
153 * TODO: Need to add a timeout in case a (remote?) resource does not respond
155 * @param ehResponse Pointer to the response from the resource.
160 OCStackResult HandleAggregateResponse(OCEntityHandlerResponse * ehResponse);
163 * Get a server request from the server request list using the specified token.
165 * @param token Token of server request.
166 * @param tokenLength Length of token.
171 OCServerRequest * GetServerRequestUsingToken (const CAToken_t token, uint8_t tokenLength);
174 * Get a server request from the server request list using the specified handle
176 * @param handle Handle of server request.
180 OCServerRequest * GetServerRequestUsingHandle (const OCRequestHandle handle);
183 * Get a server response from the server response list using the specified handle
185 * @param handle handle of server response.
190 OCServerResponse * GetServerResponseUsingHandle (const OCRequestHandle handle);
193 * Add a server request to the server request list
195 * @param request Initialized server request that is created by this function.
196 * @param coapID ID of CoAP pdu.
197 * @param delayedResNeeded Delayed response required 0=no 1=yes.
198 * @param notificationFlag TODO: remove - does not appear to be used any longer.
199 * @param method RESTful method.
200 * @param numRcvdVendorSpecificHeaderOptions Number of received vendor specific header options.
201 * @param observationOption Value of observation option.
202 * @param qos Request QOS.
203 * @param query Request query.
204 * @param rcvdVendorSpecificHeaderOptions Received vendor specific header options.
205 * @param reqJSONPayload Request JSON payload.
206 * @param requestToken Request token.
207 * @param tokenLength Request token length.
208 * @param resourceUrl URL of resource.
209 * @param reqTotalSize Total size of the request.
210 * @param acceptFormat The format requested for the payload encoding.
211 * @param devAddr Device Address.
216 OCStackResult AddServerRequest (OCServerRequest ** request, uint16_t coapID,
217 uint8_t delayedResNeeded, uint8_t notificationFlag, OCMethod method,
218 uint8_t numRcvdVendorSpecificHeaderOptions, uint32_t observationOption,
219 OCQualityOfService qos, char * query,
220 OCHeaderOption * rcvdVendorSpecificHeaderOptions,
221 uint8_t * payload, CAToken_t requestToken,
223 char * resourceUrl, size_t reqTotalSize,
224 OCPayloadFormat acceptFormat,
225 const OCDevAddr *devAddr);
228 * Form the OCEntityHandlerRequest struct that is passed to a resource's entity handler
230 * @param entityHandlerRequest pointer to the OCEntityHandlerRequest struct that is created.
231 * @param request Request handle.
232 * @param method RESTful method.
233 * @param resource Resource handle.
234 * @param queryBuf Resource query of request.
235 * @param bufReqPayload JSON payload of request.
236 * @param numVendorOptions Number of vendor options.
237 * @param vendorOptions Vendor options.
238 * @param observeAction Observe action flag.
239 * @param observeID Observe ID.
244 OCStackResult FormOCEntityHandlerRequest(
245 OCEntityHandlerRequest * entityHandlerRequest,
246 OCRequestHandle request,
249 OCResourceHandle resource,
251 OCPayloadType payloadType,
254 uint8_t numVendorOptions,
255 OCHeaderOption * vendorOptions,
256 OCObserveAction observeAction,
257 OCObservationId observeID,
261 * Find a server request in the server request list and delete
263 * @param serverRequest server request to find and delete.
265 void FindAndDeleteServerRequest(OCServerRequest * serverRequest);
267 #endif //OC_SERVER_REQUEST_H