API Functions¶

This section describes the API functions provided in the IRI host library, exposed via the iri.h header file, used to configure the IRI host and communicate with the Indy Reader Modules. The API documented within are intended to be used as is, and not modified in any way.

This section does not include API that are part of the platform ports and ipj_util example code, as those API are intended to be modified or replaced by the user.

For examples of how to use these API functions in code, see the Configuration Examples and Example Programs sections of the documentation.

`ipj_connect`¶

ipj_error ipj_connect(ipj_iri_device * iri_device, IPJ_READER_IDENTIFIER reader_identifier, ipj_connection_type connection_type, ipj_connection_params * params)

This function opens the serial port and connects the Host to the IRI device.

Parameters:

iri_device -
IRI device data structure

reader_identifier -
Identifier associated with IRI device

connection_type -
Type of connection (Serial/TCP/etc)

params -
Connection parameters (baudrate/etc) (NULL==default)

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure, register platform handlers, and connect to the IRI device (this function).

Return: ipj_error

`ipj_disconnect`¶

ipj_error ipj_disconnect(ipj_iri_device * iri_device)

This function disconnects the Host from the IRI device and closes the serial port.

Parameters:

iri_device -
IRI device data structure

User may disconnect from the IRI device after all operations are completed.

Return: ipj_error

`ipj_set`¶

Note

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_set(ipj_iri_device * iri_device, ipj_key key, uint32_t bank_index, uint32_t value_index, uint32_t value)

This function sets the value of the specified key code on the IRI device.

Parameters:

iri_device -
IRI device data structure

key -
Key code to set

bank_index -
Key code bank_index to set (applicable for key codes with more than one copy)

value_index -
Key code value_index to set (applicable for key codes with lists)

value -
Value to set

Return: ipj_error

`ipj_set_value`¶

Note

This function is a simplified version of ipj_set which assumes a bank_index and value_index of 0.

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_set_value(ipj_iri_device * iri_device, ipj_key key, uint32_t value)

This function sets the value of the specified key code on the IRI device.

Parameters:

iri_device -
IRI device data structure

key -
Key code to set

value -
Value to set

Return: ipj_error

`ipj_bulk_set`¶

Note

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_bulk_set(ipj_iri_device * iri_device, ipj_key_value * key_value, uint32_t key_value_count, ipj_key_list * key_list, uint32_t key_list_count)

This function sets the value of the specified key codes on the IRI device.

Parameters:

iri_device -
IRI device data structure

key_value -
Array of key codes and values to set

key_value_count -
Number of key codes and values to set

key_list -
Array of key codes to set (used for key codes with lists)

key_list_count -
Number of keys codes (with lists) to set

Return: ipj_error

`ipj_get`¶

Note

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_get(ipj_iri_device * iri_device, ipj_key key, uint32_t bank_index, uint32_t value_index, uint32_t * value)

This function retrieves the value of the specified key code from the IRI device.

Parameters:

iri_device -
IRI device data structure

key -
Key code to get

bank_index -
Key code bank_index to get (applicable if more than one copy of a key)

value_index -
Key code value_index to get (applicable for key code with lists)

value -
Data buffer to store retrieved value

Return: ipj_error

`ipj_get_value`¶

Note

This is a simplified version of ipj_get which assumes a bank_index and value_index of 0.

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_get_value(ipj_iri_device * iri_device, ipj_key key, uint32_t * value)

This function retrieves the value of the specified key code from the IRI device.

Parameters:

iri_device -
IRI device data structure

key -
Key code to get

value -
Data buffer to store retrieved value

Return: ipj_error

`ipj_bulk_get`¶

Note

For more details on setting and getting keys, see the Configuration Commands section.

ipj_error ipj_bulk_get(ipj_iri_device * iri_device, ipj_key_value * key_value, uint32_t key_value_count, ipj_key_list * key_list, uint32_t key_list_count)

This function retrieves the values of the specified key codes from the IRI device.

Parameters:

iri_device -
IRI device data structure

key_value -
Array of key codes to retrieve

key_value_count -
Number of key codes and values to retrieve

key_list -
Array of key codes to retrieve (used for key codes with lists)

key_list_count -
Number of keys codes (with lists) to retrieve

Return: ipj_error

`ipj_get_info`¶

ipj_error ipj_get_info(ipj_iri_device * iri_device, ipj_key key, ipj_key_info * key_info)

This function retrieves information about the specified key code from the IRI device.

Parameters:

iri_device -
IRI device data structure

key -
Key code to get info

key_info -
Information about the specified key code

Return: ipj_error

`ipj_start`¶

Note

The Configuration Examples contain a number of examples of using this API to initiate actions, including RFID, GPIO, low power mode entry, etc.

ipj_error ipj_start(ipj_iri_device * iri_device, ipj_action action)

This function starts the specified action or operation on the IRI device.

Parameters:

iri_device -
IRI device data structure

action -
Actions or operations to start

This function is used to start inventory to read tags.

Return: ipj_error

`ipj_resume`¶

Note

This feature is not available in this release and will return a E_IPJ_ERROR_NOT_IMPLEMENTED error code if called.

ipj_error ipj_resume(ipj_iri_device * iri_device, ipj_action action)

This function resumes the specified action or operation on the IRI device.

Parameters:

iri_device -
IRI device data structure

action -
Actions or operations to be resumed

This function is used to resume operations after the IRI device has halted.

Return: ipj_error

`ipj_stop`¶

ipj_error ipj_stop(ipj_iri_device * iri_device, ipj_action action)

This function stops the specified action or operation on the IRI device.

Parameters:

iri_device -
IRI device data structure

action -
Actions or operations to be stopped

This function is used to stop inventory to read tags.

Return: ipj_error

`ipj_receive`¶

Note

For more details on using this API function, see the IRI_Intro code example.

ipj_error ipj_receive(ipj_iri_device * iri_device)

This function processes incoming reports from the IRI device.

Parameters:

iri_device -
IRI device data structure

User calls this function to process incoming data. This function requests available data from the platform receive handler, buffers data, and checks for complete reports. This function returns immediately if there is not sufficient data for a report. Once a complete report is received, this function calls the report handler before returning.

User decides when to call this function. For example, User can poll or wait for an interrupt from the system. User responsibility to call this function to keep the receive buffer from overflowing.

Return: ipj_error

`ipj_reset`¶

ipj_error ipj_reset(ipj_iri_device * iri_device, ipj_reset_type reset_type)

This function resets the IRI device.

Parameters:

iri_device -
IRI device data structure

reset_type -
Type of reset to perform

State of the IRI device is not preserved across resets.

Return: ipj_error

`ipj_modify_connection`¶

Note

For more details on using this API function, see the Change Baud Rate configuration example.

ipj_error ipj_modify_connection(ipj_iri_device * iri_device, ipj_connection_type connection_type, ipj_connection_params * params)

This function modifies the serial port baud rate used to talk to an IRI device.

Parameters:

iri_device -
IRI device data structure

connection_type -
Connection modification type

params -
Connection modification parameters

Before modifying an iri connection, the user must have already successfully connected to a device.

Return: ipj_error

`ipj_suppress_set_responses`¶

ipj_error ipj_suppress_set_responses(ipj_iri_device * iri_device)

This function allows the user to suppress all ‘set’ and ‘bulk-set’ action responses generated by the reader.

Parameters:

iri_device -
IRI device data structure

The user will be responsible for checking and dealing with errors on the device.

Return: ipj_error

`ipj_resume_set_responses`¶

ipj_error ipj_resume_set_responses(ipj_iri_device * iri_device)

This function allows the user to resume generation of ‘set’ action responses by the reader.

Parameters:

iri_device -
IRI device data structure

All ‘set’ and ‘bulk-set’ actions will receive an associated response containing success/failure status of the command (This is the default)

Return: ipj_error

`ipj_set_receive_timeout_ms`¶

ipj_error ipj_set_receive_timeout_ms(ipj_iri_device * iri_device, uint32_t timeout_ms)

This function allows the user to set the amount of time the receive state machine should wait before returning a timeout error.

Parameters:

iri_device -
IRI device data structure

timeout_ms -
Timeout value in milliseconds

Return: ipj_error

`ipj_get_api_version`¶

uint32_t ipj_get_api_version()

This function returns the API version.

Return: uint32_t

`ipj_initialize_iri_device`¶

ipj_error ipj_initialize_iri_device(ipj_iri_device * iri_device)

This function initializes the IRI device data structure.

Parameters:

iri_device -
IRI device data structure

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure (this function), register platform handlers, and connect to the IRI device.

Return: ipj_error

`ipj_deinitialize_iri_device`¶

ipj_error ipj_deinitialize_iri_device(ipj_iri_device * iri_device)

This function deinitializes the IRI device data structure.

Parameters:

iri_device -
IRI device data structure

User may deinitialize IRI device after disconnecting from the IRI device. Once the IRI device is deinitialized, the User may de-allocate the IRI device data structure.

Return: ipj_error

`ipj_register_handler`¶

Note

For more details on the platform and report handlers, see the Platform and Report Handlers section.

ipj_error ipj_register_handler(ipj_iri_device * iri_device, ipj_handler_type handler_type, IPJ_VOID_PFN handler)

This function registers platform and report handlers.

Parameters:

iri_device -
IRI device data structure

handler_type -
Type of handler to register

handler -
Handler pointer

Before using an IRI device, the User application must do the following: allocate or declare IRI device data structure, initialize IRI device data structure, register platform handlers (this function or the _ext-suffixed version), and connect to the IRI device.

User application registers the following platform handlers: platform open port handler, platform close port handler, platform receive handler, platform transmit handler, and platform timestamp handler.

User application registers report handler to handle the following reports: tag operation report, error report, and stop report

Return: ipj_error

`ipj_flash_handle_loader_block`¶

ipj_error ipj_flash_handle_loader_block(ipj_iri_device * iri_device, uint32_t len, uint8_t * data)

This function takes in an IRI_Loader chunk and processes it accordingly.

Parameters:

iri_device -
IRI device data structure

len -
Length of the data chunk (in bytes)

data -
Pointer to the data chunk to be processed

Return: ipj_error

`IPJ_CLEAR_STRUCT`¶

void IPJ_CLEAR_STRUCT (struct);

IPJ_CLEAR_STRUCT is a convenience macro provided to clear out IRI related structures before use.

We recommend using this macro on every data structure passed into an IRI function to ensure proper behavior.