ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_devmsg.h File Reference

isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component. More...

#include <isf.h>
#include <isf_comm.h>
#include <isf_i2c.h>

Go to the source code of this file.

Data Structures

struct  protocol_t
 This structure contains protocol-specific function pointers and properties. More...
struct  dm_ChannelDescriptor_struct
 This structure is a declaration of a channel descriptor type. More...
struct  dm_DeviceHandle_struct
 This structure defines a handle for the device. More...

Typedefs

typedef isf_status_t(* fnInit_t )(comm_Id_t aBusId, void *apBusHandle)
 This is the function pointer signature for bus initialization.
typedef comm_State_t(* fnGetState_t )(void *apBusHandle)
 This is the function pointer signature for getting the state of the bus.
typedef isf_status_t(* fnGetConfig_t )(void *apBusHandle, void *apBusConfig)
 This is the function pointer signature for getting the configuration of the bus.
typedef isf_status_t(* fnConfigure_t )(void *apBusHandle, void *apBusConfig)
 This is the function pointer signature for setting the configuration of the bus.
typedef isf_status_t(* fnStart_t )(void *apBusHandle)
 This is the function pointer signature for starting the bus.
typedef isf_status_t(* fnStop_t )(void *apBusHandle, isf_duration_t aTimeout)
 This is the function pointer signature for stopping the bus.
typedef isf_status_t(* fnGetSlaveAt_t )(void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle)
 This is the function pointer signature for getting the slave handle.
typedef isf_status_t(* fnAcquireLock_t )(void *apBusHandle, isf_duration_t aTimeout)
 This is the function pointer signature for acquiring the lock for a particular bus.
typedef isf_status_t(* fnReleaseLock_t )(void *apBusHandle)
 This is the function pointer signature for releasing the lock for a particular bus.
typedef isf_status_t(* fnRead_t )(void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags)
 This is the function pointer signature for reading the data from a specified device.
typedef isf_status_t(* fnWrite_t )(void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags)
 This is the the function pointer signature for writing the data to a specified device.
typedef comm_Id_t dm_ChannelId_t
 This typedef is a umeric channel identifier index into an array of channels in the system.
typedef void * dm_ChannelConfig_ptr
 This structure defines the user-specified parameters for channel configuration.
typedef struct
dm_ChannelDescriptor_struct 
dm_ChannelDescriptor_t
 This structure is a declaration of a channel descriptor type.
typedef struct
dm_DeviceHandle_struct 
dm_DeviceHandle_t
 This structure defines a handle for the device.

Functions

dm_ChannelDescriptor_tdm_channel_get_descriptor (dm_DeviceHandle_t *apDeviceHandle)
 This function retrieves the channel descriptor from a device handle.
Initialization Routines
isf_status_t dm_channel_init (dm_ChannelId_t aChannelId, dm_ChannelDescriptor_t *apChannelDescriptor)
 This function initializes a channel.
isf_status_t dm_channel_configure (dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr aChannelConfig)
 This function reconfigures an already initialized channel.
Queries and Status
comm_State_t dm_channel_get_state (dm_ChannelDescriptor_t *apChannelDescriptor)
 This function returns the channel state.
isf_status_t dm_channel_get_config (dm_ChannelDescriptor_t *apChannelDescriptor, dm_ChannelConfig_ptr aChannelConfig)
 This function returns the current channel configuration.
Device Control Routines
isf_status_t dm_device_open (dm_ChannelDescriptor_t *apChannelDescriptor, comm_Address_t aDeviceAddr, dm_DeviceHandle_t *apDeviceHandle)
 This function creates a device handle for a device at a specified channel address.
isf_status_t dm_device_close (dm_DeviceHandle_t *apDeviceHandle)
 This function closes a device.
Channel Control Routines
isf_status_t dm_channel_start (dm_ChannelDescriptor_t *apChannelDescriptor)
 This function starts a channel.
isf_status_t dm_channel_stop (dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
 This function stops a channel.
isf_status_t dm_channel_acquire_lock (dm_ChannelDescriptor_t *apChannelDescriptor, isf_duration_t aTimeout)
 This function locks the channel for exclusive access.
isf_status_t dm_channel_release_lock (dm_ChannelDescriptor_t *apChannelDescriptor)
 This function releases exclusive channel access.
Device Operation Routines
isf_status_t dm_device_read (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apReadCmd, comm_MessageBuffer_t *apReadBuffer)
 This function reads from a device.
isf_status_t dm_device_readx (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apReadCmd, comm_MessageBuffer_t *apReadBuffer, comm_Flags_t aFlags)
 This function reads from a device with extended behavior.
isf_status_t dm_device_write (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apWriteCmd)
 This function writes to a device.
isf_status_t dm_device_writex (dm_DeviceHandle_t *apDeviceHandle, comm_Command_t *apWriteCmd, comm_Flags_t aFlags)
 This function writes data to a device with extended write behavior.

Detailed Description

isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component.

File: isf_devmsg.h

Copyright (c) 2012, Freescale Semiconductor, Inc.

Definition in file isf_devmsg.h.


Typedef Documentation

typedef void* dm_ChannelConfig_ptr

This structure defines the user-specified parameters for channel configuration.

This type allows the device messaging APIs to handle a protocol-specific configuration pointer opaquely until it is passed to the specific protocol functions that use the data.

Definition at line 103 of file isf_devmsg.h.

This structure is a declaration of a channel descriptor type.

The channel descriptor contains the bus and protocol information required by the device messaging functions to safely use a channel for communications. The members are ordered to maintain natural alignment without inserting padding bytes.

This typedef is a umeric channel identifier index into an array of channels in the system.

Definition at line 94 of file isf_devmsg.h.

This structure defines a handle for the device.

The device handle contains the information required by the device messaging functions to address and communicate with a slave device.

typedef isf_status_t(* fnAcquireLock_t)(void *apBusHandle, isf_duration_t aTimeout)

This is the function pointer signature for acquiring the lock for a particular bus.

Definition at line 62 of file isf_devmsg.h.

typedef isf_status_t(* fnConfigure_t)(void *apBusHandle, void *apBusConfig)

This is the function pointer signature for setting the configuration of the bus.

Definition at line 46 of file isf_devmsg.h.

typedef isf_status_t(* fnGetConfig_t)(void *apBusHandle, void *apBusConfig)

This is the function pointer signature for getting the configuration of the bus.

Definition at line 42 of file isf_devmsg.h.

typedef isf_status_t(* fnGetSlaveAt_t)(void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle)

This is the function pointer signature for getting the slave handle.

Definition at line 58 of file isf_devmsg.h.

typedef comm_State_t(* fnGetState_t)(void *apBusHandle)

This is the function pointer signature for getting the state of the bus.

Definition at line 38 of file isf_devmsg.h.

typedef isf_status_t(* fnInit_t)(comm_Id_t aBusId, void *apBusHandle)

This is the function pointer signature for bus initialization.

Definition at line 34 of file isf_devmsg.h.

typedef isf_status_t(* fnRead_t)(void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags)

This is the function pointer signature for reading the data from a specified device.

Definition at line 70 of file isf_devmsg.h.

typedef isf_status_t(* fnReleaseLock_t)(void *apBusHandle)

This is the function pointer signature for releasing the lock for a particular bus.

Definition at line 66 of file isf_devmsg.h.

typedef isf_status_t(* fnStart_t)(void *apBusHandle)

This is the function pointer signature for starting the bus.

Definition at line 50 of file isf_devmsg.h.

typedef isf_status_t(* fnStop_t)(void *apBusHandle, isf_duration_t aTimeout)

This is the function pointer signature for stopping the bus.

Definition at line 54 of file isf_devmsg.h.

typedef isf_status_t(* fnWrite_t)(void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags)

This is the the function pointer signature for writing the data to a specified device.

Definition at line 74 of file isf_devmsg.h.


Function Documentation

This function locks the channel for exclusive access.

dm_channel_acquire_lock() serializes multi-client access. Each channel user must acquire a lock prior to sending device messages. While holding the channel lock, no other clients may perform any channel operations. Therefore, it is important to release the lock with dm_channel_release_lock() as soon as practical.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be started.
[in]aTimeoutThe time to wait for the lock before returning without the lock. The timeout parameter may be set to zero to wait for calls that fail to return without acquiring the lock, or wait as long as necessary for the lock to be acquired.
Returns:
dm_channel_acquire_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel lock is acquired.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • The actual time spent in the call may be longer than the specified timeout due to the granularity of the timer used.
  • A valid device handle should be passed into the function.
  • apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_channel_configure ( dm_ChannelDescriptor_t apChannelDescriptor,
dm_ChannelConfig_ptr  aChannelConfig 
)

This function reconfigures an already initialized channel.

A channel may be reconfigured after initialization. Calls to dm_channel_configure() after initialization will override any previous configuration values and must be made while the channel state is COMM_STATE_STOPPED. The typical usage involves retrieving the current configuration using dm_channel_get_config(), making modifications to the returned configuration, and then calling dm_channel_configure() with the updated configuration. The channel is implicitly locked during the configuration.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be configured.
[in]aChannelConfigThe channel configuration used during initialization.
Returns:
dm_channel_configure() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel was reconfigured successfully.
COMM_ERROR_STOPis returned when the channel was not STOPPED.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • apChannelDescriptor must be valid. A valid channel descriptor is created when the dm_channel_init() function call is successfully returned.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_channel_get_config ( dm_ChannelDescriptor_t apChannelDescriptor,
dm_ChannelConfig_ptr  aChannelConfig 
)

This function returns the current channel configuration.

A channel may be queried for the current configuration.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be queried.
[out]aChannelConfigThe address of a channel configuration to be filled.
Returns:
dm_channel_get_config() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel configuration is retrieved successfully.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
Constraints:
The following constraints must be observed when using this function:
  • apChannelDescriptor must be valid. A valid channel descriptor is created when the dm_channel_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib

This function retrieves the channel descriptor from a device handle.

dm_channel_get_descriptor() returns the channel descriptor associated with the channel on which the device resides.

Parameters:
[in]apDeviceHandleHandle of device connected on the channel of interest.
Returns:
dm_channel_get_descriptor() returns a value of type dm_ChannelDescriptor_t which is pointer to an object.
Return values:
NULLis returned when the specified device handle is invalid.
Constraints:
None
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib

This function returns the channel state.

A channel may be queried for its current state.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be queried.
Returns:
dm_channel_get_state() returns a value of type comm_State_t indicating the current state of the channel.
Return values:
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
Constraints:
The following constraints must be observed when using this function:
  • apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_channel_init ( dm_ChannelId_t  aChannelId,
dm_ChannelDescriptor_t apChannelDescriptor 
)

This function initializes a channel.

A channel must be initialized prior to use. Initialization creates the channel and initializes the data structures required to manage the channel. The channel is implicitly locked during the initialization.

Parameters:
[in]aChannelIdThe ID of the channel to initialize. This is an index into the array of known channels that can be used.
[out]apChannelDescriptorThe address of the channel descriptor structure to be initialized.
Returns:
dm_channel_init() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel initialized successfully and the apChannelDescriptor structure reference has been populated with initialized channel data.
COMM_ERROR_NOEXISTis returned when the supplied channel identifier does not exist.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_INITis returned when the channel could not be initialized.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • aChannelId must be in the range of the known channel identifiers as defined in isf_sysconf_comms.h
Reentrant: Yes
Link Libraries:
isf_core.lib

This function releases exclusive channel access.

dm_channel_release_lock() is used to relinquish exclusive access on a paricular channel. It is the inverse of dm_channel_acquire_lock().

Parameters:
[in]apChannelDescriptorThe handle of the channel to unlock.
Returns:
dm_channel_release_lock() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel released successfully.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_LOCKis returned when no lock was held on the specified channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib

This function starts a channel.

dm_channel_start() enables communications with an initialized channel. This call enables the hardware peripherals associated with the channel. The channel is implicitly locked during the start operation.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be started.
Returns:
dm_channel_start() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel was started successfully.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_channel_stop ( dm_ChannelDescriptor_t apChannelDescriptor,
isf_duration_t  aTimeout 
)

This function stops a channel.

dm_channel_stop() disables an initialized channel and stops communications with the channel. This call disables the hardware peripherals associated with the channel. The channel is implicitly locked during the stop operation.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be stopped.
[in]aTimeoutThe time to wait for the channel to stop before returning a failure. The timeout parameter may be set to zero to never return without stopping the channel, i.e. wait as long as required for the channel to stop.
Returns:
dm_channel_stop() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the channel is successfully stopped.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib

This function closes a device.

The dm_device_close() function is used when no further communication with the device is needed. A closed device should not be passed to dm_device_read() or dm_device_write(). The channel is implicitly locked during the close operation.

Parameters:
[in]apDeviceHandleThe address of the DeviceHandle to be closed.
Returns:
dm_device_open() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the device changes to closed.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_device_open ( dm_ChannelDescriptor_t apChannelDescriptor,
comm_Address_t  aDeviceAddr,
dm_DeviceHandle_t apDeviceHandle 
)

This function creates a device handle for a device at a specified channel address.

The dm_device_open() function may be used to get a handle to a device at a known channel address. The channel is implicity locked during the open.

Parameters:
[in]apChannelDescriptorThe handle of the channel to be queried.
[in]aDeviceAddrThe known address of a device.
[out]apDeviceHandleThe address of a DeviceHandle to be filled. dm_device_open() fills the provided device handle structure with valid data when a device is found at the specified address.
Returns:
dm_channel_configure() returns a value of type isf_status_t indicating the success or failure of the function call.
Return values:
ISF_SUCCESSis returned when the device is located and a valid handle is returned.
COMM_ERROR_NOEXISTis returned when a device does not exist at the specified address.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_STOPis returned when the channel has not been started.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
Constraints:
The following constraints must be observed when using this function:
  • apChannelDescriptor must be valid. A valid channel descriptor is created when the dm_channel_init() function call returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_device_read ( dm_DeviceHandle_t apDeviceHandle,
comm_Command_t apReadCmd,
comm_MessageBuffer_t apReadBuffer 
)

This function reads from a device.

dm_device_read() reads data from the specified device. The supplied command is sent to the device triggering the device to return some data. Any data returned by the device is read and placed in the provided read buffer. Note that if the command sent does not trigger the device to return data, the dm_device_read() simply returns 0 bytes read. The device is implicitly locked during the read.

Parameters:
[in]apDeviceHandleThe handle to the device from which to read.
[in]apReadCmdThe read command to send to the device.
[in]apReadBufferBuffer address where any returned data is placed.
Returns:
dm_device_read() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when data from the device was read successfully.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_BUF_SIZEis returned when the provided buffer is too small to hold all the data or the number of bytes read is zero.
COMM_ERROR_STOPis returned when the read is invoked on a stopped channel.
COMM_ERROR_NO_ACKis returned when no acknowledgment was received from the device.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
COMM_ERROR_DEV_CLOSEDis returned when the read is invoked on a closed device.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_device_readx ( dm_DeviceHandle_t apDeviceHandle,
comm_Command_t apReadCmd,
comm_MessageBuffer_t apReadBuffer,
comm_Flags_t  aFlags 
)

This function reads from a device with extended behavior.

dm_device_readx() reads data from the specified device. The supplied command is sent to the device which may trigger the device to return some data. Any data returned by the device is read and placed in the provided read buffer. dm_device_readx() modifies the basic behavior of the read command by passing a set of bit flags to the underlying protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol being used and to pass the appropriate flag values. The device is implicitly locked during the extension read.

Parameters:
[in]apDeviceHandleThe handle to the device from which to read.
[in]apReadCmdThe read command to transmit to the device.
[out]apReadBufferAddress of the buffer in which to place the read data.
[in]aFlagsA set of bit flags controlling the behavior of the read.
Returns:
dm_device_readx() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the device was read successfully.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_BUF_SIZEThe provided buffer is too small to hold all the data or the number of bytes to read is zero.
COMM_ERROR_STOPis returned when the read is invoked on a stopped channel.
COMM_ERROR_NO_ACKis returned when no acknowledgment was received from the device.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
COMM_ERROR_DEV_CLOSEDis returned when the read is invoked on a closed device.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_device_write ( dm_DeviceHandle_t apDeviceHandle,
comm_Command_t apWriteCmd 
)

This function writes to a device.

dm_device_write() writes data to the specified device. The device is implicitly locked during the write.

Parameters:
[in]apDeviceHandleThe handle of the device to which to write.
[in]apWriteCmdThe command to send to the device.
Returns:
dm_device_write() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the device was written successfully.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_STOPis returned when the write is invoked on a stopped channel.
COMM_ERROR_NO_ACKis returned when no acknowledgment was received from the device.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
COMM_ERROR_DEV_CLOSEDis returned when the write is invoked on a closed device.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib
isf_status_t dm_device_writex ( dm_DeviceHandle_t apDeviceHandle,
comm_Command_t apWriteCmd,
comm_Flags_t  aFlags 
)

This function writes data to a device with extended write behavior.

dm_device_writex() writes data to the specified device. This function modifies the basic behavior of the write command by passing a set of bit flags to the underlying protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol used and to pass the appropriate flag values. As an example, if it is known that the underlying device is an I2C bus, it is possible to set the appropriate flag values to explicitly control the RepeatedStart behavior at the conclusion of the dm_device_write() call. The device is implicitly locked during the extension write.

Parameters:
[in]apDeviceHandleThe handle of the device to which to write.
[in]apWriteCmdThe command to send to the device.
[in]aFlagsA set of bit flags controlling the behavior of the write.
Returns:
dm_device_writex() returns a value of type isf_status_t indicating whether the operation was successful or unsuccessful.
Return values:
ISF_SUCCESSis returned when the data was successfully written to the device.
COMM_ERROR_INITis returned when the channel handle refers to a non-initialized channel.
COMM_ERROR_STOPis returned when the write is invoked on a stopped channel.
COMM_ERROR_NO_ACKis returned when no acknowledgment was received from the device.
COMM_ERROR_NULL_PTRis returned when a NULL pointer argument was passed into the function.
COMM_ERROR_TIME_OUTis returned when the request could not be fulfilled in the specified timeout period.
COMM_ERROR_LOCKis returned when a lock could not be acquired properly.
COMM_ERROR_DEV_CLOSEDis returned when the write is invoked on a closed device.
Constraints:
The following constraints must be observed when using this function:
  • apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function returns successfully.
Reentrant: Yes
Link Libraries:
isf_core.lib