Macros
#define	OM_MAX_PATH (256)

Typedefs
typedef void(*	OmDownloadCallback) (void *, int, OM_DOWNLOAD_STATUS, int)

typedef void(*	OmDownloadChunkCallback) (void , int, void , int, int)

Enumerations
enum	OM_DOWNLOAD_STATUS { OM_DOWNLOAD_NONE, OM_DOWNLOAD_ERROR, OM_DOWNLOAD_PROGRESS, OM_DOWNLOAD_COMPLETE, OM_DOWNLOAD_CANCELLED }

Functions
int	OmSetDownloadCallback (OmDownloadCallback downloadCallback, void *reference)

int	OmSetDownloadChunkCallback (OmDownloadChunkCallback downloadChunkCallback, void *reference)

int	OmGetDataFileSize (int deviceId)

int	OmGetDataFilename (int deviceId, char *filenameBuffer)

int	OmGetDataRange (int deviceId, int dataBlockSize, int dataOffsetBlocks, int dataNumBlocks, OM_DATETIME startTime, OM_DATETIME *endTime)

int	OmBeginDownloading (int deviceId, int dataOffsetBlocks, int dataLengthBlocks, const char *destinationFile)

int	OmBeginDownloadingReference (int deviceId, int dataOffsetBlocks, int dataLengthBlocks, const char destinationFile, void reference)

int	OmQueryDownload (int deviceId, OM_DOWNLOAD_STATUS downloadStatus, int downloadValue)

int	OmWaitForDownload (int deviceId, OM_DOWNLOAD_STATUS downloadStatus, int downloadValue)

int	OmCancelDownload (int deviceId)

Detailed Description

Functions to provide simultaneous download from multiple devices.

The size, time-range, and internal chunking of the data buffer on the device is determined with a call to OmGetDataRange().

A background download of data from a device is initiated with a call to OmBeginDownloading(), and cancelled with OmCancelDownload().

The user typically registers a 'callback' function, using OmDownloadCallback(), that will be asynchronously called by the API with updated information about the download progress.

Alternatively, OmQueryDownload() may be called to determine the download progress.

Applications that wish to synchronously block until the download completes (or is cancelled or fails), can call OmWaitForDownload().

See also: Example code download.c, for an example of how to use the data download functions of the API.

Macro Definition Documentation

◆ OM_MAX_PATH

#define OM_MAX_PATH (256)

Macro for the maximum path length of a data filename.

Since: 1.2

Definition at line 840 of file omapi.h.

Typedef Documentation

◆ OmDownloadCallback

typedef void(* OmDownloadCallback) (void *, int, OM_DOWNLOAD_STATUS, int)

Download update callback function type.

Called for download progress, completion, cancellation, or failure. Callback functions take a user-defined reference pointer, a device ID, a status code, and a value.

See also: OmSetDownloadCallback

Definition at line 863 of file omapi.h.

◆ OmDownloadChunkCallback

typedef void(* OmDownloadChunkCallback) (void *, int, void *, int, int)

Download chunk callback function type.

Called for download chunks. Callback functions take a user-defined reference pointer, a device ID, a buffer pointer, a file position and a buffer size.

See also: OmSetDownloadCallback

Since: 1.4

Definition at line 873 of file omapi.h.

Enumeration Type Documentation

◆ OM_DOWNLOAD_STATUS

enum OM_DOWNLOAD_STATUS

Download states used in the OmDownloadCallback handler.

See also: OmDownloadCallback, OmSetDownloadCallback

Enumerator
OM_DOWNLOAD_NONE	No download information.
OM_DOWNLOAD_ERROR	Data download failed with an error (the value parameter to OmDownloadCallback indicates a diagnostic error code)
OM_DOWNLOAD_PROGRESS	Data download progress (the value parameter to OmDownloadCallback indicates progress percentage)
OM_DOWNLOAD_COMPLETE	Data download completed successfully.
OM_DOWNLOAD_CANCELLED	Data download was cancelled cleanly.

Definition at line 847 of file omapi.h.

Function Documentation

◆ OmBeginDownloading()

int OmBeginDownloading	(	int	deviceId,
		int	dataOffsetBlocks,
		int	dataLengthBlocks,
		const char *	destinationFile
	)

Begin downloading the data from the current device.

Once the download has successfully started, the call returns immediately, and the download continues in another thread. The user-specified download callback is called to notify the user about download progress, completion, cancellation, or failure.

Parameters

deviceId	Identifier of the device.
dataOffsetBlocks	Start offset of the download (in blocks), typically 0.
dataLengthBlocks	Length of the data to download (in blocks), -1 = all.
destinationFile	File to write to (will truncate any existing file). If NULL, will read the file but not write to a file – this can be used in conjunction with the OmSetDownloadChunkCallback() so the application can stream the data to another location.

Returns: OM_OK if successfully started the download, an error code otherwise.

See also: OmSetDownloadCallback(), OmSetDownloadChunkCallback(), OmWaitForDownload(), OmCancelDownload()

◆ OmBeginDownloadingReference()

int OmBeginDownloadingReference	(	int	deviceId,
		int	dataOffsetBlocks,
		int	dataLengthBlocks,
		const char *	destinationFile,
		void *	reference
	)

Begin downloading the data from the current device, passing an additional reference.

Once the download has successfully started, the call returns immediately, and the download continues in another thread. The user-specified download callback is called to notify the user about download progress, completion, cancellation, or failure.

Parameters

deviceId	Identifier of the device.
dataOffsetBlocks	Start offset of the download (in blocks), typically 0.
dataLengthBlocks	Length of the data to download (in blocks), -1 = all.
destinationFile	File to write to (will truncate any existing file). If NULL, will read the file but not write to a file – this can be used in conjunction with the OmSetDownloadChunkCallback() so the application can stream the data to another location.
reference	An additional reference to pass to the download callbacks – if NULL, the reference given when registering the callback will be used instead.

Returns: OM_OK if successfully started the download, an error code otherwise.

See also: OmBeginDownloading(), OmSetDownloadCallback(), OmSetDownloadChunkCallback(), OmWaitForDownload(), OmCancelDownload()

Since: 1.4

◆ OmCancelDownload()

int OmCancelDownload ( int deviceId )

Cancel the current download of the data on the specified device.

Remarks: If the download is still in progress, this will cancel the download (which will trigger a call to the user's download callback, if specified).

Parameters

deviceId Identifier of the device.

Returns: OM_OK if successfully cancelled the download, an error code otherwise.

See also: OmSetDownloadCallback, OmBeginDownloading()

◆ OmGetDataFilename()

int OmGetDataFilename	(	int	deviceId,
		char *	filenameBuffer
	)

Return the path to the data file for the specified device.

Parameters

	deviceId	Identifier of the device.
[out]	filenameBuffer	A buffer to receive the data filename (of size OM_MAX_PATH).

See also: OmReaderOpen()

Since: 1.2

◆ OmGetDataFileSize()

int OmGetDataFileSize ( int deviceId )

Return the data file size of the specified device.

Parameters

deviceId Identifier of the device.

See also: OmBeginDownloading()

Since: 1.4

◆ OmGetDataRange()

int OmGetDataRange	(	int	deviceId,
		int *	dataBlockSize,
		int *	dataOffsetBlocks,
		int *	dataNumBlocks,
		OM_DATETIME *	startTime,
		OM_DATETIME *	endTime
	)

Read the size, time-range, and internal chunking of the data buffer.

Parameters

	deviceId	Identifier of the device.
[out]	dataBlockSize	A pointer to a value to receive the block size of the data (512 bytes), or NULL if not required.
[out]	dataOffsetBlocks	A pointer to a value to receive the offset of the data in blocks (same as the header size: 2 blocks), or NULL if not required.
[out]	dataNumBlocks	A pointer to a value to receive the size of the data buffer in blocks, or NULL if not required.
[out]	startTime	A pointer for the start time of the data, or NULL if not required.
[out]	endTime	A pointer for the end time of the data, or NULL if not required.

Returns: OM_OK if successful, an error code otherwise.

◆ OmQueryDownload()

int OmQueryDownload	(	int	deviceId,
		OM_DOWNLOAD_STATUS *	downloadStatus,
		int *	downloadValue
	)

This function queries the status of the specified device's asynchronous download.

Remarks: Using the user-specified download callback would be sufficient for most applications.

Parameters

	deviceId	Identifier of the device.
[out]	downloadStatus	Current status of the download (whether none, in-progress, completed, cancelled or failed).
[out]	downloadValue	A pointer to be used to store a value associated with the download status. If the downloadStatus is OM_DOWNLOAD_PROGRESS, this stores the percent progress. If the downloadStatus is OM_DOWNLOAD_ERROR, this stores a diagnostic code. Can be NULL if not required.

Returns: OM_OK if successfully obtained the download status, an error code otherwise.

See also: OmSetDownloadCallback()

◆ OmSetDownloadCallback()

int OmSetDownloadCallback	(	OmDownloadCallback	downloadCallback,
		void *	reference
	)

Sets the callback function that is called for download progress, completion, cancellation, or failure.

Parameters

	downloadCallback	The function to call on download activity, 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.

◆ OmSetDownloadChunkCallback()

int OmSetDownloadChunkCallback	(	OmDownloadChunkCallback	downloadChunkCallback,
		void *	reference
	)

Sets the chunk callback function that is called when a new download chunk is received.

Parameters

	downloadChunkCallback	The function to call on download activity, 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.4

◆ OmWaitForDownload()

int OmWaitForDownload	(	int	deviceId,
		OM_DOWNLOAD_STATUS *	downloadStatus,
		int *	downloadValue
	)

This function waits for the specified device's asynchronous download to finish.

The call returns immediately if a download is not in progress, or will blocks and return when the download completes, is cancelled, or fails.

Remarks: This call is useful for single-threaded, non-interactive applications.; The user-specified download callback, if specified, is still called (and is useful for progress reports).

Parameters

	deviceId	Identifier of the device.
[out]	downloadStatus	Final status of the download (whether completed, cancelled or failed).
[out]	downloadValue	A pointer to be used to store a final value for the download - if the downloadStatus is OM_DOWNLOAD_ERROR, this stores a diagnostic code. Can be NULL if not required.

Returns: OM_OK if successfully waited for the download, an error code otherwise.

See also: OmSetDownloadCallback(), OmBeginDownloading()

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OM_MAX_PATH

Typedef Documentation

◆ OmDownloadCallback

◆ OmDownloadChunkCallback

Enumeration Type Documentation

◆ OM_DOWNLOAD_STATUS

Function Documentation

◆ OmBeginDownloading()

◆ OmBeginDownloadingReference()

◆ OmCancelDownload()

◆ OmGetDataFilename()

◆ OmGetDataFileSize()

◆ OmGetDataRange()

◆ OmQueryDownload()

◆ OmSetDownloadCallback()

◆ OmSetDownloadChunkCallback()

◆ OmWaitForDownload()