Release notes
****************************************************************************
Release date: Dec 6th, 2014.
OS: Ubuntu 12.0.4 and above
Requires boost version 1.55 to build.
Code buildable in gcc 4.6.3 and above.
NOTE: Boost is not distributed but should be installed in the Ubuntu machine.
*****************************************************************************

Release commit number: de31af

What is new?

Features:
---------

Slow Response:
--------------
This release includes slow response feature which allows a resource entity handler to provide
a 'slow response' to a client request. If a request is received but the server cannot response
immediately (example, response data is not available), then the server can response at a later
time. The same API is used for both immediate and slow response.

GET/PUT request on the batch interface of a collection resource using the default collection
entity handler will result in each pointed resource’s entity handler being invoked, after which:
a) if all pointed resources of the collection are local and not-slow, an aggregated
response will be sent
b) if collection includes slow local resource(s), an aggregated response is sent only after
the slowest resource’s entity handler responds with a payload. If one or more slow resource
entity handlers do not respond, no response is sent to the request, i.e. there is no timeout
mechanism in current release

Samples demonstrating slow response:
simpleserver and simpleclient in C++
ocserverslow and occlientslow in C

Security:
----------
1. OCStack is compiled with security only if a valid libtinydtls.a is available
under oic-resource/resource/csdk/tinydtls directory.
2. This release provides an API to set device identity and PSK credentials.
3. Security is NOT supported for Arduino platform.

JSON serialization using Cereal libray
--------------------------------------
This release includes modifications which consists of using
open source library cereal to perform JSON serialization
and de-serialization in C++ layer. (NOTE: previously we were
using boost::property tree for JSON parsing)

NOTE: For a nested (array of array of array..) JSON value, we limit to 3-level deep nesting.
Refer AttributeValue.h for more details.

------------
API changes:
------------

--------------------------------------------
Class OCPlatform (Header file: OCPlatform.h)
--------------------------------------------

*****************
sendResponse API
*****************

This new API allows the application entity handler to send response to a request.
This API is used in sending a response immediately (if available) or in cases of
slow response. Due to this change, signature of application entity handler has
been modified. This introduces changes in application entity handler code.
Please see below.
All C++ samples demonstrate the use of sendResponse API.

--------------------------------------------
Header file: OCApi.h
--------------------------------------------

typedef std::function<OCEntityHandlerResult(
    const std::shared_ptr<OCResourceRequest>)> EntityHandler;

Signature of application entity handler has changed. New signature consists only of
one parameter which is OCResourceRequest pointer. Response is formed and sent via
sendResponse API. All C++ samples are updated to showcase this modification.

----------------------------------------------------------
Class OCResourceRequest (Header file: OCResourceRequest.h)
----------------------------------------------------------

********************
getRequestHandle API
********************

This new API allows the application entity handler to retrieve request handle
from the incoming request.
All C++ samples demonstrate the use of getRequestHandle API.

*********************
getResourceHandle API
*********************

This new API allows the application entity handler to retrieve resource handle
from the incoming request.
All C++ samples demonstrate the use of getResourceHandle API.

-------------------------------------------------------------
Class OCResourceResponse (Header file: OCResourceResponse.h)
-------------------------------------------------------------

********************
setRequestHandle API
********************

This new API allows the application entity handler to set request handle in
the response.
All C++ samples demonstrate the use of setRequestHandle API.

*********************
setResourceHandle API
*********************

This new API allows the application entity handler to set resource handle in
the response.
All C++ samples demonstrate the use of setResourceHandle API.

*********************
setResponseResult API
*********************

This new API allows the application entity handler to set result in
the response.
All C++ samples demonstrate the use of setResponseResult API.

-------------------------------------------------------------
Header file: OCStack.h
-------------------------------------------------------------

***************************
OCDoResponse API
***************************

This new C API allows the application entity handler to send response to a request.
This API is used in sending a response immediately (if available) or in cases of
slow response.

-------------------------------------------------------------
Header file: OCSecurity.h
-------------------------------------------------------------

***************************
OCSetDtlsPskCredentials API
***************************

This new API allows to set DTLS PSK credentials.

------------
Notes:
------------

Known issues:
-------------
1. When observation is used, server shutdown causes an error (segmentation fault).

Active discovery-
1. In case of unicast presence with rt, only one rt is permitted per IP address for
subscribePresence. If multiple subscriptions are done, only first subscribePresence’s rt is used.
2. For multicast presence, server shutdown (ungraceful) scenario is not notified to the client,
but graceful shutdowns are notified.
3. IOT 85

Issues Fixed:
-------------
1. IOT 65 (Stopping presence subscription gets infinite callback to handlePresence)
2. IOT 79 (3 Presence Notifications when a resource is created on the server)

General notes:
--------------
Maximum length of URI supported is 64 bytes (sent from the client)
Maximum length of query supported is 64 bytes (sent from the client)
Maximum length of request from client and response from server for Arduino is is 256 bytes
Maximum length of request from client and response from server for non-Ardunio is is 1024 bytes

OIC base supports Arduino WiFi shield.
This support has been tested with Arduino Mega 2560 and with Arduino 1.0.5 WiFi library.
Please refer to oic-resource/csdk/README file for building OIC base with WiFi support.

-------------
How to build:
-------------

REFER https://oic-review.01.org/gerrit for more details on getting oic-resource repo.
If the code is not cloned:
Clone the oic-resource repo using this command: git clone oic:oic-resource

NOTE: If the repo is already cloned, use 'git pull' inside oic-resource folder to get the
latest code.

In repo oic-resource, root folder consists of 'resource' folder.  Inside OIC folder there
is a Makefile.

Inside oic-resource directory, use 'make'to build the entire OIC code. This would build the C++ SDK,
core(i.e base) and samples.

Use 'make BUILD=debug' to build the entire OIC code in debug mode. This would build the C++ SDK,
core(i.e base) and samples.

--------
Samples:
--------

A basic sample for hosting a resource on a server and a sample for client for discovering resources
are provided here:
Simple server sample location: oic-resource/examples/simpleserver.cpp
Simple client sample location: oic-resource/examples/simpleclient.cpp
Server and client mode (mode type both) location: oic-resource/examples/simpleclientserver.cpp
Simpleserver and simpleclient samples also provide examples for doing POST operation.
Simpleserver also demonstrates slow response case for a GET request.

Garage samples provide usage of OCRepresentation, get/set attribute values
oic-resource/examples/garageclient.cpp
oic-resource/examples/garageserver.cpp

Fridge samples provide usage of constructResourceObject API, std bind
(for mapping request and responses), default
device entity handler, header options support and Delete operation.
oic-resource/examples/fridgeclient.cpp
oic-resource/examples/fridgeserver.cpp

Presence samples provides examples to use presence APIs
Sample with basic presence feature for server side: oic-resource/examples/presenceserver.cpp
Sample with basic presence feature for client side: oic-resource/examples/presenceclient.cpp

Room samples provides examples to use resource collection.
oic-resource/examples/roomclient.cpp
oic-resource/examples/roomserver.cpp

After building the code in oic-resource, executables for samples are in directory named
'oic-resource/samples/release'.
After building the code in oic-resource, executables are in directory named 'oic-resource/release'.

