Yoctopuce Yocto-GPS User Manual Download

Page: 139 / 572

http://127.0.0.1:4444/bySerial/YGNSSMK1-12345/dataLogger.json?id=latitude

&utc=1389801080

19.3. Using dynamic libraries

The low level Yoctopuce API is available under several formats of dynamic libraries written in C. The
sources are available with the C++ API. If you use one of these low level libraries, you do not need
the

VirtualHub

anymore.

Filename

Platform

libyapi.dylib

Max OS X

libyapi-amd64.so

Linux Intel (64 bits)

libyapi-armel.so

Linux ARM EL

libyapi-armhf.so

Linux ARM HL

libyapi-i386.so

Linux Intel (32 bits)

yapi64.dll

Windows (64 bits)

yapi.dll

Windows (32 bits)

These dynamic libraries contain all the functions necessary to completely rebuild the whole high level
API in any language able to integrate these libraries. This chapter nevertheless restrains itself to
describing basic use of the modules.

Driving a module

The three essential functions of the low level API are the following:

int

yapiInitAPI

(

int

connection_type,

char

*errmsg

)

;

int

yapiUpdateDeviceList

(

int

forceupdate,

char

*errmsg

)

;

int

yapiHTTPRequest

(

char

*device,

char

*request,

char

* buffer,

int

buffsize,

int

*fullsize,

char

*errmsg

)

;

The

yapiInitAPI

function initializes the API and must be called once at the beginning of the program.

For a USB type connection, the

connection_type

parameter takes value 1. The

errmsg

parameter

must point to a 255 character buffer to retrieve a potential error message. This pointer can also point
to

null

. The function returns a negative integer in case of error, zero otherwise.

The

yapiUpdateDeviceList

manages the inventory of connected Yoctopuce modules. It must be

called at least once. To manage hot plug and detect potential newly connected modules, this function
must be called at regular intervals. The

forceupdate

parameter must take value 1 to force a hardware

scan. The

errmsg

parameter must point to a 255 character buffer to retrieve a potential error

message. This pointer can also point to

null

. The function returns a negative integer in case of error,

zero otherwise.

Finally, the

yapiHTTPRequest

function sends HTTP requests to the module REST API. The

device

parameter contains the serial number or the logical name of the module which you want to reach.
The

request

parameter contains the full HTTP request (including terminal line breaks).

buffer

points

to a character buffer long enough to contain the answer.

buffsize

is the size of the buffer.

fullsize

is a

pointer to an integer to which will be assigned the actual size of the answer. The

errmsg

parameter

must point to a 255 character buffer to retrieve a potential error message. This pointer can also point
to

null

. The function returns a negative integer in case of error, zero otherwise.

The format of the requests is the same as the one described in the

VirtualHub et HTTP GET

section.

All the character strings used by the API are strings made of 8-bit characters: Unicode and UTF8 are
not supported.

The resutlt returned in the buffer variable respects the HTTP protocol. It therefore includes an HTTP
header. This header ends with two empty lines, that is a sequence of four ASCII characters 13, 10,
13, 10.

Here is a sample program written in pascal using the

yapi.dll

DLL to read and then update the

luminosity of a module.

19. Using with unsupported languages

www.yoctopuce.com

133