opn_interface

Header file containing the API for the libopn_driver library.

Version: EGFS0035 (0.0.3.5)

Includes: <CoreFoundation/CoreFoundation.h>

Discussion

This API controls the OPN 2001 driver, a user-space driver in the form of a dynamically linked library. Note that this library must be loaded at load time, meaning it is a dependent library of any client code that uses it. You must include (and call the functions in) this header in your projects, and add the library to your projects, to use the library. The library's install location is "@executable_path/../ Frameworks" (although, the path may be changed with install_name_tool).

The libopn_driver library utilizes the Carbon Event Manager to signal client code of three possible events: 1) the OPN has been removed, 2) the OPN has been inserted, or 3) the OPN has data. The particulars of each event (its class and kind, which together, compose its type) can be accessed via API functions defined in this file. However, it is the responsibility of any client code utilizing this library to implement event handler functions, install these functions, and run the application event loop. Examples of how to do this are illustrated in the project "opn_test." More information about the Carbon Event Manager, and how to use it, can be found in the Apple Developer documentation. See the Carbon Event Manager Programming Guide for details.

Note that this library is dependent upon the Carbon, CoreFoundation, and IOKit frameworks. These are part of any normal OS X installation, and though it's probably impossible for OS X to run without them, it's noted here for completeness. This library should run on both x86 and PPC flavors of OS X.

This driver should only be used with OPN firmware version RBBV0120 and later.

Functions

clearDataCmd: Erases stored barcodes from the device.
CreateOPNInterface: Instantiates and initializes the libopn_driver library.
DestroyOPNInterface: Cleans up and destroys the instance of the libopn_driver library.
disablePolling: Disable the generation of the device-has-data event when data is available in the device.
enablePolling: Enable the generation of the device-has-data event when data is available in the device.
getASCIIMode: Retrieves the data encoding of the barcodes read by the device.
getBarcode: Retrieves a read barcode.
getCodeType: Looks up and retrieves a symbology name from a symbology ID.
getDeviceID: Retrieves the device ID of the device.
getEventClass: Retrieves a value used to signify the class of events generated by the library.
getEventKindDataAvailable: Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-has-data event.
getEventKindInsert: Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-insertion event.
getEventKindRemove: Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-removal event.
getLibraryVersion: Retrieves the version of this library.
getParamCmd: Retrieves the associated value of a parameter.
getProtocolVersion: Retrieves the protocol version of the device.
getRetryCount: Retrieves the retry count for the interrogate command.
getRTCMode: Retrieves a value indicating whether the barcodes read by the device have a timestamp appended to them, indicating when they were read.
getSoftwareVersion: Retrieves the software version of the device.
getSystemStatus: Retrieves the system status of the device.
getTimeCmd: Gets the RTC (real-time clock) timestamp from the device.
interrogateCmd: Queries the device for its Device ID, Software Version, Protocol Version, and System Status.
isDataAvailable: Indicates whether or not the device has barcode data.
powerDownCmd: Shuts down the device.
readData: Reads barcodes from the device.
setDefaultsCmd: Restores the device to a default state.
setParamCmd: Sets the associated value of a parameter.
setRetryCount: Sets the retry count for the interrogate command.
setTimeCmd: Sets the RTC (real-time clock) time of the device.
timeStamp2String: Converts a 4-byte timestamp buffer into a formatted date/time string.

clearDataCmd

Erases stored barcodes from the device.

extern "C" SInt32 clearDataCmd(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

If you read the barcodes stored in the device, and don't call this function to clear them, then on the next read, the previously read barcodes will be read again, because they haven't been erased.

CreateOPNInterface

Instantiates and initializes the libopn_driver library.

extern "C" OPNInterface CreateOPNInterface();

Return Value

An opaque pointer of type OPNInterface, needed to call other functions.

Discussion

This function must be called before all others, except for getEventClass, getEventKindInsert, getEventKindRemove, and getEventKindDataAvailable.

DestroyOPNInterface

Cleans up and destroys the instance of the libopn_driver library.

extern "C" void DestroyOPNInterface(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Discussion

This function should be called when the interface to the device is no longer necessary. For example, in a client application's cleanup code.

disablePolling

Disable the generation of the device-has-data event when data is available in the device.

extern "C" SInt32 disablePolling(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

GENERAL_ERROR on error, or STATUS_OK on success.

Discussion

Calling this function stop the generation of the device-has-data event.

enablePolling

Enable the generation of the device-has-data event when data is available in the device.

extern "C" SInt32 enablePolling(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

GENERAL_ERROR on error, or STATUS_OK on success.

Discussion

Calling this function will poll the device intermittently for whether or not it has data. If it does, it will generate the device-has-data event, which must be handled by client code.

getASCIIMode

Retrieves the data encoding of the barcodes read by the device.

extern "C" SInt32 getASCIIMode(
    OPNInterface interface,
    bool *AM);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
AM: A pointer to a boolean variable that will contain, on return, true if the data encoding is ASCII, and false if it's binary.

Return Value

BAD_PARAM if AM is NULL, or STATUS_OK on success.

Discussion

readData must be called before this function returns any meaningful data.

getBarcode

Retrieves a read barcode.

extern "C" SInt32 getBarcode(
    OPNInterface interface,
    char *BarcodeData,
    UInt32 BarcodeNumber,
    UInt32 *BarcodeDataLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
BarcodeData: A pointer to a buffer that will contain the data of the read barcode.
BarcodeNumber: A number, within the domain of 0 <= n <= N (where N is the total number of read barcodes, got by readData), signifying the barcode to be returned in BarcodeData.
BarcodeDataLength: Input: a pointer to a variable holding the size of BarcodeData. Output: the pointer is updated to hold the number of bytes read into BarcodeData.

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

Probably best used in a loop designed to retrieve every read barcode.

Note that calling this function does not erase the retrieved barcode from the driver's internal storage of read barcodes.

The first byte of the returned barcode data is the barcode's length (the length doesn't include the first byte). The second byte is the barcode symbology, which can be passed to getCodeType to retrieve the symbology name. The last four bytes, if the RTC timestamp is set to be appended to each barcode the device reads, is the timestamp of when the barcode was read (which can be passed to timeStamp2String to return a formatted date/time string). All of the bytes between the barcode symbology byte, and (potentially) the RTC timestamp bytes, compose the actual barcode data.

getCodeType

Looks up and retrieves a symbology name from a symbology ID.

extern "C" SInt32 getCodeType(
    OPNInterface interface,
    char *CodeName,
    UInt32 CodeNameLength,
    UInt8 CodeID);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
CodeName: A pointer to a buffer that will contain the symbology name.
CodeNameLength: The size of the CodeName buffer.
CodeID: The symbology ID used to look up the symbology name.

Return Value

BAD_PARAM if CodeName is NULL; GENERAL_ERROR on an error; or STATUS_OK on success.

Discussion

The driver must be loaded and CreateOPNInterface called before this function can be called.

getDeviceID

Retrieves the device ID of the device.

extern "C" SInt32 getDeviceID(
    OPNInterface interface,
    char *DevID,
    UInt32 DevIDLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
DevID: A pointer to a buffer that will contain the data composing the device ID.
DevIDLength: The size of the DevID buffer.

Return Value

BAD_PARAM if DevID is NULL or DevIDLength is less than DEVICE_ID_SIZE; STATUS_OK on success.

Discussion

One of the command functions must be called before this function returns any meaningful data.

getEventClass

Retrieves a value used to signify the class of events generated by the library.

extern "C" UInt32 getEventClass();

Return Value

An integer value signifying the event class for library-generated events.

Discussion

This function may be called before CreateOPNInterface.

An event type is made up of an event class and an event kind. Event types are essentially how events get matched to event handlers. The event class returned by this function is defined by the library, meaning that this function must be utilized when installing and/or handling the insertion, removal, or device-has-data events.

getEventKindDataAvailable

Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-has-data event.

extern "C" UInt32 getEventKindDataAvailable();

Return Value

An integer value signifying the event kind for a library-generated device-has-data event.

Discussion

This function may be called before CreateOPNInterface.

An event type is made up of an event class and an event kind. Event types are essentially how events get matched to event handlers. The event kind returned by this function is defined by the library, meaning that this function must be utilized when installing and/or handling the device-has-data event.

getEventKindInsert

Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-insertion event.

extern "C" UInt32 getEventKindInsert();

Return Value

An integer value signifying the event kind for a library-generated insertion event.

Discussion

This function may be called before CreateOPNInterface.

An event type is made up of an event class and an event kind. Event types are essentially how events get matched to event handlers. The event kind returned by this function is defined by the library, meaning that this function must be utilized when installing and/or handling the insertion event.

getEventKindRemove

Retrieves a value used to specify what kind of event, within a class of events, a particular event is. In this case, a library-generated device-removal event.

extern "C" UInt32 getEventKindRemove();

Return Value

An integer value signifying the event kind for a library-generated removal event.

Discussion

This function may be called before CreateOPNInterface.

An event type is made up of an event class and an event kind. Event types are essentially how events get matched to event handlers. The event kind returned by this function is defined by the library, meaning that this function must be utilized when installing and/or handling the removal event.

getLibraryVersion

Retrieves the version of this library.

extern "C" SInt32 getLibraryVersion(
    OPNInterface interface,
    char *VersionString,
    UInt32 VersionStringLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
VersionString: A pointer to a buffer that will contain the driver version string.
VersionStringLength: The size of the VersionString buffer.

Return Value

BAD_PARAM if VersionString is NULL or VersionStringLength is less than LIBRARY_VERSION_SIZE; STATUS_OK on success.

Discussion

The driver version string is 8 characters (e.g. RABS0030).

getParamCmd

Retrieves the associated value of a parameter.

extern "C" SInt32 getParamCmd(
    OPNInterface interface,
    UInt8 Param,
    char *ParamValue,
    UInt32 *ParamValueLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
Param: A value signifying the parameter to obtain the associated value for.
ParamValue: A pointer to a buffer that will, on return, hold the associated value of the parameter.
ParamValueLength: Input: a pointer to a variable holding the size of ParamValue. Output: the pointer is updated to hold the number of bytes read into ParamValue.

Return Value

A status code. See the status code defines for the possible returned codes.

getProtocolVersion

Retrieves the protocol version of the device.

extern "C" SInt32 getProtocolVersion(
    OPNInterface interface,
    UInt32 *PV);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
PV: A pointer to an integer variable that will contain, on return, the protocol version.

Return Value

BAD_PARAM if PV is NULL, or STATUS_OK on success.

Discussion

One of the command functions must be called before this function returns any meaningful data.

getRetryCount

Retrieves the retry count for the interrogate command.

extern "C" SInt32 getRetryCount(
    OPNInterface interface,
    UInt32 *Retries);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
Retries: A pointer to an integer variable that will contain, on return, the retry count.

Return Value

BAD_PARAM if Retries is NULL, or STATUS_OK on success.

Discussion

The interrogate command will attempt to execute up to the number of times returned in Retries if it doesn't execute successfully before then.

getRTCMode

Retrieves a value indicating whether the barcodes read by the device have a timestamp appended to them, indicating when they were read.

extern "C" SInt32 getRTCMode(
    OPNInterface interface,
    bool *RTC);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
RTC: A pointer to a boolean variable that will contain, on return, true if the timestamp data is appended, and false if not.

Return Value

BAD_PARAM if RTC is NULL, or STATUS_OK on success.

Discussion

readData must be called before this function returns any meaningful data.

getSoftwareVersion

Retrieves the software version of the device.

extern "C" SInt32 getSoftwareVersion(
    OPNInterface interface,
    char *SV,
    UInt32 SVLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
SV: A pointer to a buffer that will contain the data composing the software version.
SVLength: The size of the SV buffer.

Return Value

BAD_PARAM if SV is NULL or SVLength is less than SOFTWARE_VERSION_SIZE; STATUS_OK on success.

Discussion

One of the command functions must be called before this function returns any meaningful data.

getSystemStatus

Retrieves the system status of the device.

extern "C" SInt32 getSystemStatus(
    OPNInterface interface,
    UInt32 *SysStat);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
SysStat: A pointer to an integer variable that will contain, on return, the system status.

Return Value

BAD_PARAM if SysStat is NULL, or STATUS_OK on success.

Discussion

One of the command functions must be called before this function returns any meaningful data.

getTimeCmd

Gets the RTC (real-time clock) timestamp from the device.

extern "C" SInt32 getTimeCmd(
    OPNInterface interface,
    UInt8 *TimeBuffer,
    UInt32 *BufferLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
TimeBuffer: A pointer to a byte buffer to hold the timestamp. The buffer should be of size TIME_BUFFER_SIZE.
BufferLength: Input: a pointer to a variable holding the size of TimeBuffer. Output: the pointer is updated to hold the number of bytes read into TimeBuffer.

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

TimeBuffer should be passed to the timeStamp2String function in order to convert the TimeBuffer into a human-readable date and time string.

interrogateCmd

Queries the device for its Device ID, Software Version, Protocol Version, and System Status.

extern "C" SInt32 interrogateCmd(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

After this function has been called, the getDeviceID function, the getSoftwareVersion function, the getProtocolVersion function, and the getSystemStatus function will return appropriate values in their passed-in buffers.

isDataAvailable

Indicates whether or not the device has barcode data.

extern "C" SInt32 isDataAvailable(
    OPNInterface interface,
    bool *DataAvailable);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
DataAvailable: A pointer to a boolean that will, on return, be true if there is barcode data to be read, and false if there is not.

Return Value

A status code. See the status code defines for the possible returned codes.

powerDownCmd

Shuts down the device.

extern "C" SInt32 powerDownCmd(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

The usefulness or relevance of this function is dubious.

readData

Reads barcodes from the device.

extern "C" SInt32 readData(
    OPNInterface interface,
    UInt32 *NumberOfCodes);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
NumberOfCodes: A pointer to a value that will, on return, contain the number of barcodes that have been read from the device.

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

This function must be called to read barcodes from the device. However, the barcodes are only returned to client code via getBarcode.

Note that the driver's internal storage of read barcodes is erased on every successful call to this function. The barcodes are only erased from the device, however, when clearDataCmd is called.

setDefaultsCmd

Restores the device to a default state.

extern "C" SInt32 setDefaultsCmd(
    OPNInterface interface);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

This function will reset any parameters that have been changed via setParamCmd.

setParamCmd

Sets the associated value of a parameter.

extern "C" SInt32 setParamCmd(
    OPNInterface interface,
    UInt8 Param,
    char *ParamValue,
    UInt32 ParamValueLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
Param: A value signifying the parameter to set the associated value for.
ParamValue: A pointer to a buffer that holds the new associated value of the parameter.
ParamValueLength: The size of ParamValue.

Return Value

A status code. See the status code defines for the possible returned codes.

setRetryCount

Sets the retry count for the interrogate command.

extern "C" SInt32 setRetryCount(
    OPNInterface interface,
    UInt32 Retries);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
Retries: The new value for the retry count.

Return Value

BAD_PARAM if Retries is less than 0 or greater than 9, or STATUS_OK on success.

Discussion

The interrogate command will attempt to execute up to the number of times specified in Retries if it doesn't execute successfully before then.

setTimeCmd

Sets the RTC (real-time clock) time of the device.

extern "C" SInt32 setTimeCmd(
    OPNInterface interface,
    UInt8 *TimeBuffer,
    UInt32 BufferLength);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
TimeBuffer: A pointer to a byte buffer to holding the timestamp to set. The buffer should be of size TIME_BUFFER_SIZE.
BufferLength: The size of TimeBuffer.

Return Value

A status code. See the status code defines for the possible returned codes.

timeStamp2String

Converts a 4-byte timestamp buffer into a formatted date/time string.

extern "C" SInt32 timeStamp2String(
    OPNInterface interface,
    char *TimeString,
    UInt32 TimeStringLength,
    UInt8 *TimeStamp);

Parameters

interface: The OPNInterface opaque pointer returned by CreateOPNInterface().
TimeString: A pointer to a buffer to hold the formatted date/time string.
TimeStringLength: The size of the TimeString buffer.
TimeStamp: A 4-byte buffer containing an RTC timestamp, such as the one returned via getTimeCmd.

Return Value

A status code. See the status code defines for the possible returned codes.

Discussion

Make sure the size of the TimeString buffer is big enough to fit any formatted date/time string. A size of 31 (NUL terminator included) ought to do.

#defines

BAD_PARAM

Return value of a function that indicates there was a bad parameter to the function.

#define BAD_PARAM -2

COMMAND_LRC_ERROR

Return value of a function that indicates that the CRC check on written or read data failed.

#define COMMAND_LRC_ERROR -7

COMMUNICATIONS_ERROR

Return value of a function that indicates there was a communication error.

#define COMMUNICATIONS_ERROR -1

DEVICE_ID_SIZE

Expected size of the buffer holding the Device ID, including the trailing null character.

#define DEVICE_ID_SIZE 9

GENERAL_ERROR

Return value of a function that indicates that some error occurred.

#define GENERAL_ERROR -9

INVALID_COMMAND_NUMBER

Return value of a function that indicates that the command sent to the driver was not defined.

#define INVALID_COMMAND_NUMBER -4

LIBRARY_VERSION_SIZE

Expected size of the buffer holding the driver version, including the trailing null character.

#define LIBRARY_VERSION_SIZE 9

RECEIVED_CHARACTER_ERROR

Return value of a function that indicates that the function encountered a value it did not expect.

#define RECEIVED_CHARACTER_ERROR -8

SETUP_ERROR

Return value of a function that indicates the driver instance was in a state that didn't permit it to carry out the function.

#define SETUP_ERROR -3

SOFTWARE_VERSION_SIZE

Expected size of the buffer holding the Software Version, including the trailing null character.

#define SOFTWARE_VERSION_SIZE 9

STATUS_OK

Return value of a function that executes with no errors.

#define STATUS_OK 0

TIME_BUFFER_SIZE

Expected size of the buffer holding time data for getTimeCmd() and setTimeCmd().

#define TIME_BUFFER_SIZE 6