File content as of revision 29:004c318e63fa:

**NOTICE: This library is not finished, do not depend on it for anything, it
will have potentially significant bugs.**

# libexositecoap

This is the C library for interacting with the Exosite One Platform. It aims to
be fast, efficient, and flexible. Platform operations are queued up and then
performed with non-blocking calls so that your application can continue to do
local processing while waiting for the network transactions to complete.

## Status

This is a very early release, there will be bugs. If you find one, please open
an issue on https://github.com/exosite-labs/libexositecoap/issues. Pull requests
are also highly encouraged. At some point in the future you will be required to
show a test case that fails before your patch and succeeds after it, but there
aren't any tests yet, so just describe the problem.

Because this is an alpha release, please don't use it in production.
Backwards-incompatible changes will very likely have to be made when bugs are
found, but you are highly encouraged to use it for testing. The examples do
work and the changes to the interface won't be too substantial.

Only a limited set of the final features have been implemented. Currently, reads
writes, and subscribes work. You can not yet activate or interact with content.

The inline documentation is incomplete and is probably wrong in many places,
don't pay too much attention to it. You should be able to figure out most of the
usage from the examples and the function prototypes.

## About

This library uses the concept of "operations" (ops) for all interactions with
the OneP. One operation is a single read, write, or subscription of a single
dataport. There are two classes of ops, single shot and sustained. Read and
write are single shot operations. That means that you queue the operation then
process until it either succeeds or fails. Subscribe is a sustained operation,
that means that you queue it once then the library will do everything in it's
power to keep it active.

## Usage

This section won't explain everything, at least not until we decide that the API
is stable, see the examples folder for real uses.

### Most Common Use

You have to hold the memory for the ops, it's up to you if you want to use
malloc, create an array of `exo_op`s then call `exo_op_init()` on that array to
initialize it. Next add any sustained operations that you want. Then add any
one-shot operations you want to call immediately. Once you have all the
operations you want queued up, call `exo_operate()` until it returns `EXO_IDLE`,
this means that it has nothing more to do and all of the queued single-shot
operations have succeeded or failed and that all of the queued sustained
sustained operations are in a waiting state and are not expecting any immediate
responses. This is the time to do any operations that will take more than a
couple hundred milliseconds.