resource/releaseNotes/Dec6th2014.txt

   1 Release notes
   2 ****************************************************************************
   3 Release date: Dec 6th, 2014.
   4 OS: Ubuntu 12.0.4 and above
   5 Requires boost version 1.55 to build.
   6 Code buildable in gcc 4.6.3 and above.
   7 NOTE: Boost is not distributed but should be installed in the Ubuntu machine.
   8 *****************************************************************************
   9
  10 Release commit number: de31af
  11
  12 What is new?
  13
  14 Features:
  15 ---------
  16
  17 Slow Response:
  18 --------------
  19 This release includes slow response feature which allows a resource entity handler to provide
  20 a 'slow response' to a client request. If a request is received but the server cannot response
  21 immediately (example, response data is not available), then the server can response at a later
  22 time. The same API is used for both immediate and slow response.
  23
  24 GET/PUT request on the batch interface of a collection resource using the default collection
  25 entity handler will result in each pointed resource’s entity handler being invoked, after which:
  26 a) if all pointed resources of the collection are local and not-slow, an aggregated
  27 response will be sent
  28 b) if collection includes slow local resource(s), an aggregated response is sent only after
  29 the slowest resource’s entity handler responds with a payload. If one or more slow resource
  30 entity handlers do not respond, no response is sent to the request, i.e. there is no timeout
  31 mechanism in current release
  32
  33 Samples demonstrating slow response:
  34 simpleserver and simpleclient in C++
  35 ocserverslow and occlientslow in C
  36
  37 Security:
  38 ----------
  39 1. OCStack is compiled with security only if a valid libtinydtls.a is available
  40 under oic-resource/resource/csdk/tinydtls directory.
  41 2. This release provides an API to set device identity and PSK credentials.
  42 3. Security is NOT supported for Arduino platform.
  43
  44 JSON serialization using Cereal libray
  45 --------------------------------------
  46 This release includes modifications which consists of using
  47 open source library cereal to perform JSON serialization
  48 and de-serialization in C++ layer. (NOTE: previously we were
  49 using boost::property tree for JSON parsing)
  50
  51 NOTE: For a nested (array of array of array..) JSON value, we limit to 3-level deep nesting.
  52 Refer AttributeValue.h for more details.
  53
  54 ------------
  55 API changes:
  56 ------------
  57
  58 --------------------------------------------
  59 Class OCPlatform (Header file: OCPlatform.h)
  60 --------------------------------------------
  61
  62 *****************
  63 sendResponse API
  64 *****************
  65
  66 This new API allows the application entity handler to send response to a request.
  67 This API is used in sending a response immediately (if available) or in cases of
  68 slow response. Due to this change, signature of application entity handler has
  69 been modified. This introduces changes in application entity handler code.
  70 Please see below.
  71 All C++ samples demonstrate the use of sendResponse API.
  72
  73 --------------------------------------------
  74 Header file: OCApi.h
  75 --------------------------------------------
  76
  77 typedef std::function<OCEntityHandlerResult(
  78     const std::shared_ptr<OCResourceRequest>)> EntityHandler;
  79
  80 Signature of application entity handler has changed. New signature consists only of
  81 one parameter which is OCResourceRequest pointer. Response is formed and sent via
  82 sendResponse API. All C++ samples are updated to showcase this modification.
  83
  84 ----------------------------------------------------------
  85 Class OCResourceRequest (Header file: OCResourceRequest.h)
  86 ----------------------------------------------------------
  87
  88 ********************
  89 getRequestHandle API
  90 ********************
  91
  92 This new API allows the application entity handler to retrieve request handle
  93 from the incoming request.
  94 All C++ samples demonstrate the use of getRequestHandle API.
  95
  96 *********************
  97 getResourceHandle API
  98 *********************
  99
 100 This new API allows the application entity handler to retrieve resource handle
 101 from the incoming request.
 102 All C++ samples demonstrate the use of getResourceHandle API.
 103
 104 -------------------------------------------------------------
 105 Class OCResourceResponse (Header file: OCResourceResponse.h)
 106 -------------------------------------------------------------
 107
 108 ********************
 109 setRequestHandle API
 110 ********************
 111
 112 This new API allows the application entity handler to set request handle in
 113 the response.
 114 All C++ samples demonstrate the use of setRequestHandle API.
 115
 116 *********************
 117 setResourceHandle API
 118 *********************
 119
 120 This new API allows the application entity handler to set resource handle in
 121 the response.
 122 All C++ samples demonstrate the use of setResourceHandle API.
 123
 124 *********************
 125 setResponseResult API
 126 *********************
 127
 128 This new API allows the application entity handler to set result in
 129 the response.
 130 All C++ samples demonstrate the use of setResponseResult API.
 131
 132 -------------------------------------------------------------
 133 Header file: OCStack.h
 134 -------------------------------------------------------------
 135
 136 ***************************
 137 OCDoResponse API
 138 ***************************
 139
 140 This new C API allows the application entity handler to send response to a request.
 141 This API is used in sending a response immediately (if available) or in cases of
 142 slow response.
 143
 144 -------------------------------------------------------------
 145 Header file: OCSecurity.h
 146 -------------------------------------------------------------
 147
 148 ***************************
 149 OCSetDtlsPskCredentials API
 150 ***************************
 151
 152 This new API allows to set DTLS PSK credentials.
 153
 154 ------------
 155 Notes:
 156 ------------
 157
 158 Known issues:
 159 -------------
 160 1. When observation is used, server shutdown causes an error (segmentation fault).
 161
 162 Active discovery-
 163 1. In case of unicast presence with rt, only one rt is permitted per IP address for
 164 subscribePresence. If multiple subscriptions are done, only first subscribePresence’s rt is used.
 165 2. For multicast presence, server shutdown (ungraceful) scenario is not notified to the client,
 166 but graceful shutdowns are notified.
 167 3. IOT 85
 168
 169 Issues Fixed:
 170 -------------
 171 1. IOT 65 (Stopping presence subscription gets infinite callback to handlePresence)
 172 2. IOT 79 (3 Presence Notifications when a resource is created on the server)
 173
 174 General notes:
 175 --------------
 176 Maximum length of URI supported is 64 bytes (sent from the client)
 177 Maximum length of query supported is 64 bytes (sent from the client)
 178 Maximum length of request from client and response from server for Arduino is is 256 bytes
 179 Maximum length of request from client and response from server for non-Ardunio is is 1024 bytes
 180
 181 OIC base supports Arduino WiFi shield.
 182 This support has been tested with Arduino Mega 2560 and with Arduino 1.0.5 WiFi library.
 183 Please refer to oic-resource/csdk/README file for building OIC base with WiFi support.
 184
 185 -------------
 186 How to build:
 187 -------------
 188
 189 REFER https://oic-review.01.org/gerrit for more details on getting oic-resource repo.
 190 If the code is not cloned:
 191 Clone the oic-resource repo using this command: git clone oic:oic-resource
 192
 193 NOTE: If the repo is already cloned, use 'git pull' inside oic-resource folder to get the
 194 latest code.
 195
 196 In repo oic-resource, root folder consists of 'resource' folder.  Inside OIC folder there
 197 is a Makefile.
 198
 199 Inside oic-resource directory, use 'make'to build the entire OIC code. This would build the C++ SDK,
 200 core(i.e base) and samples.
 201
 202 Use 'make BUILD=debug' to build the entire OIC code in debug mode. This would build the C++ SDK,
 203 core(i.e base) and samples.
 204
 205 --------
 206 Samples:
 207 --------
 208
 209 A basic sample for hosting a resource on a server and a sample for client for discovering resources
 210 are provided here:
 211 Simple server sample location: oic-resource/examples/simpleserver.cpp
 212 Simple client sample location: oic-resource/examples/simpleclient.cpp
 213 Server and client mode (mode type both) location: oic-resource/examples/simpleclientserver.cpp
 214 Simpleserver and simpleclient samples also provide examples for doing POST operation.
 215 Simpleserver also demonstrates slow response case for a GET request.
 216
 217 Garage samples provide usage of OCRepresentation, get/set attribute values
 218 oic-resource/examples/garageclient.cpp
 219 oic-resource/examples/garageserver.cpp
 220
 221 Fridge samples provide usage of constructResourceObject API, std bind
 222 (for mapping request and responses), default
 223 device entity handler, header options support and Delete operation.
 224 oic-resource/examples/fridgeclient.cpp
 225 oic-resource/examples/fridgeserver.cpp
 226
 227 Presence samples provides examples to use presence APIs
 228 Sample with basic presence feature for server side: oic-resource/examples/presenceserver.cpp
 229 Sample with basic presence feature for client side: oic-resource/examples/presenceclient.cpp
 230
 231 Room samples provides examples to use resource collection.
 232 oic-resource/examples/roomclient.cpp
 233 oic-resource/examples/roomserver.cpp
 234
 235 After building the code in oic-resource, executables for samples are in directory named
 236 'oic-resource/samples/release'.
 237 After building the code in oic-resource, executables are in directory named 'oic-resource/release'.
 238