API initialization and device discovery

Macros
#define	OM_VERSION   108

Typedefs
typedef void(*	OmLogCallback) (void *, const char *)
typedef void(*	OmDeviceCallback) (void *, int, OM_DEVICE_STATUS)

Enumerations
enum	OM_DEVICE_STATUS { OM_DEVICE_REMOVED, OM_DEVICE_CONNECTED }

Functions
int	OmStartup (int version)
int	OmShutdown (void)
int	OmSetLogStream (int fd)
int	OmSetLogCallback (OmLogCallback logCallback, void *reference)
int	OmSetDeviceCallback (OmDeviceCallback deviceCallback, void *reference)
int	OmGetDeviceIds (int *deviceIds, int maxDevices)

Detailed Description

Functions to support API initialization and device discovery. The API must be initialized before first use with OmStartup(), and shut down after use with OmShutdown().

To be notified when a device is added or removed from the system, the user can register a 'callback' function with OmSetDeviceCallback().

Alternatively, users may call OmGetDeviceIds() at any time to list all of the currently connected devices.

See also

Example code test.c, download.c, clear.c and deploy.c for examples of how to use the initialization and device discovery functions of the API.

Macro Definition Documentation

OM_VERSION

#define OM_VERSION   108

A numeric code for current API version defined in this header file.

Remarks

This can be used to detect a DLL version incompatibility in OmStartup().

See also

OmStartup()

Definition at line 225 of file omapi.h.

Typedef Documentation

OmDeviceCallback

typedef void(* OmDeviceCallback) (void *, int, OM_DEVICE_STATUS)

Device change callback function type.

Called for device addition or removal. Callback functions take a user-defined reference pointer, a device ID, and a state code.

See also

OmSetDeviceCallback

Definition at line 300 of file omapi.h.

OmLogCallback

typedef void(* OmLogCallback) (void *, const char *)

Log callback function type.

Called for API log messages. Callback functions take a user-defined reference pointer, and a log message.

See also

OmSetLogCallback

Since

1.2

Definition at line 270 of file omapi.h.

Enumeration Type Documentation

OM_DEVICE_STATUS

enum OM_DEVICE_STATUS

Device states used in the OmDeviceCallback handler.

See also

OmDeviceCallback, OmSetDeviceCallback

Enumerator
OM_DEVICE_REMOVED	Device is being removed, or is already removed.
OM_DEVICE_CONNECTED	Device has been connected.

Definition at line 287 of file omapi.h.

Function Documentation

OmGetDeviceIds()

int OmGetDeviceIds	(	int *	deviceIds,
		int	maxDevices
	)

Obtains the device IDs of all connected devices.

Call

OmGetDeviceIds(NULL, 0) 

to get the number of devices connected.

Parameters

[out]	deviceIds	A pointer to a buffer used to return the device IDs. May be NULL if maxDevices = 0.
	maxDevices	The maximum number of device IDs the supplied buffer can store.

Return values

>=0	the actual number of devices present, which may be more or less than maxDevices passed.
<0	An error code.

See also

clear.c, deploy.c, test.c for examples of use.

OmSetDeviceCallback()

int OmSetDeviceCallback	(	OmDeviceCallback	deviceCallback,
		void *	reference
	)

Sets the callback function that is called whenever a device is added or removed.

Parameters

	deviceCallback	The function to call when a device is added or removed, or NULL to remove the callback.
[in]	reference	A user-defined reference to pass to the callback function (or NULL if unwanted).

Returns

OM_OK if successful, an error code otherwise.

See also

download.c for an example.

OmSetLogCallback()

int OmSetLogCallback	(	OmLogCallback	logCallback,
		void *	reference
	)

Sets the callback function that is called whenever an API log message is written.

Parameters

	logCallback	The function to call when a log message is written, or NULL to remove the callback.
[in]	reference	A user-defined reference to pass to the callback function (or NULL if unwanted).

Returns

OM_OK if successful, an error code otherwise.

Since

1.2

OmSetLogStream()

int OmSetLogStream

(

int

fd

)

Sets the stream to use for log messages.

Note

This can be called at any time.

Parameters

fd	The file descriptor to use. Specify -1 for none; fileno(stderr) for standard error; or fileno(fopen("log.txt", "wt")) for a file.

Returns

OM_OK if successful, an error code otherwise.

Since

1.2

OmShutdown()

int OmShutdown

(

void

)

Shuts down the Open Movement API.

This call frees resources used by the API.

Note

Any incomplete downloads will be cancelled (and, if specified, the OmDownloadCallback function will be called).

Once called, functions that require OmStartup() may not be called unless OmStartup() is successfully called again.

Returns

OM_OK if successful, an error code otherwise.

See also

OmStartup()

OmStartup()

int OmStartup

(

int

version

)

Initializes the Open Movement API.

Allocates required resources for the API, initializes its state, and initiates device discovery.

Note

OmStartup() Must be called before most other functions in the API.
Exceptions are: OmSetLogStream(), OmSetLogCallback(), OmErrorString(), OmSetDeviceCallback(), OmSetDownloadCallback(), and all OmReaderXXX() functions.

If the OmDeviceCallback has already been set, it will be called for all devices identified at start-up.

Once successfully initialized, the caller must call OmShutdown() when finished with the API.

Parameters

version

The version number of the API required (use OM_VERSION).

Returns

OM_OK if successful, error code otherwise.

See also

OmShutdown()