| ISF 1.1 Intelligent Sensing Framework

- Main Page
- Data Structures
- Files
- Sensor Adapters

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_devmsg.h
Go to the documentation of this file.

    00001 /*!
    00002 ********************************************************************************
    00003 * File: isf_devmsg.h
    00004 *
    00005 * Copyright (c) 2012, Freescale Semiconductor, Inc.
    00006 *
    00007 *******************************************************************************/
    00008 /*!
    00009 * @file isf_devmsg.h
    00010 * @brief  \b isf_devmsg.h defines the API definitions and types for the Intelligent Sensing (ISF) Device Messaging (DM) component.
    00011 */
    00012 #ifndef INCLUDE_DEVICE_MESSAGING_H
    00013 #define INCLUDE_DEVICE_MESSAGING_H
    00014
    00015 #include <isf.h>
    00016 #include <isf_comm.h>
    00017 #include <isf_i2c.h>
    00018
    00019 /*******************
    00020 ** Macro Definitions
    00021 */
    00022
    00023 /**************
    00024 ** Enumerations
    00025 */
    00026
    00027 /*********************
    00028 ** Structures and Typedefs
    00029 */
    00030
    00031 /**
    00032  * @brief This is the function pointer signature for bus initialization.
    00033  */
    00034 typedef isf_status_t  (*fnInit_t)       (comm_Id_t aBusId, void *apBusHandle);
    00035 /**
    00036  * @brief This is the function pointer signature for getting the state of the bus.
    00037  */
    00038 typedef comm_State_t   (*fnGetState_t)   (void *apBusHandle);
    00039 /**
    00040  * @brief This is the function pointer signature for getting the configuration of the bus.
    00041  */
    00042 typedef isf_status_t  (*fnGetConfig_t)  (void *apBusHandle, void *apBusConfig);
    00043 /**
    00044  * @brief This is the function pointer signature for setting the configuration of the bus.
    00045  */
    00046 typedef isf_status_t  (*fnConfigure_t)  (void *apBusHandle, void *apBusConfig);
    00047 /**
    00048  * @brief This is the function pointer signature for starting the bus.
    00049  */
    00050 typedef isf_status_t  (*fnStart_t)      (void *apBusHandle);
    00051 /**
    00052  * @brief This is the function pointer signature for stopping the bus.
    00053  */
    00054 typedef isf_status_t  (*fnStop_t)       (void *apBusHandle, isf_duration_t aTimeout);
    00055 /**
    00056  * @brief This is the function pointer signature for getting the slave handle.
    00057  */
    00058 typedef isf_status_t  (*fnGetSlaveAt_t) (void *apBusHandle, comm_Address_t aSlaveAddr, void *apSlaveHandle);
    00059 /**
    00060  * @brief This is the function pointer signature for acquiring the lock for a particular bus.
    00061  */
    00062 typedef isf_status_t  (*fnAcquireLock_t)(void *apBusHandle, isf_duration_t aTimeout);
    00063 /**
    00064  * @brief This is the function pointer signature for releasing the lock for a particular bus.
    00065  */
    00066 typedef isf_status_t  (*fnReleaseLock_t)(void *apBusHandle);
    00067 /**
    00068  * @brief This is the function pointer signature for reading the data from a specified device.
    00069  */
    00070 typedef isf_status_t  (*fnRead_t)       (void *apSlaveHandle, void *apReadCmd, void *apReadBuffer, comm_Flags_t aFlags);
    00071 /**
    00072  * @brief This is the the function pointer signature for writing the data to a specified device.
    00073  */
    00074 typedef isf_status_t  (*fnWrite_t)      (void *apSlaveHandle, void *apWriteCmd, comm_Flags_t aFlags);
    00075 /**
    00076  * @brief This structure contains protocol-specific function pointers and properties.
    00077  */
    00078 typedef struct {
    00079     fnInit_t        fnInit;         /*!< Initialize a channel.                               */
    00080     fnGetState_t    fnGetState;     /*!< Get the state of a channel.                         */
    00081     fnGetConfig_t   fnGetConfig;    /*!< Get the current channel configuration.              */
    00082     fnConfigure_t   fnConfigure;    /*!< Reconfigure an already initialized channel.         */
    00083     fnStart_t       fnStart;        /*!< Start a channel.                                    */
    00084     fnStop_t        fnStop;         /*!< Stop a channel.                                     */
    00085     fnGetSlaveAt_t  fnGetSlaveAt;   /*!< Get the handle to a slave device at a known address.*/
    00086     fnAcquireLock_t fnAcquireLock;  /*!< Lock the channel for exclusive access.              */
    00087     fnReleaseLock_t fnReleaseLock;  /*!< Release exclusive access.                           */
    00088     fnRead_t        fnRead;         /*!< Read from a device.                                 */
    00089     fnWrite_t       fnWrite;        /*!< Write to a device.                                  */
    00090 } protocol_t;
    00091
    00092 /*! @brief This typedef is a umeric channel identifier  index into an array of channels
    00093  * in the system. */
    00094 typedef comm_Id_t dm_ChannelId_t;
    00095
    00096 /*! @brief This structure defines the user-specified parameters for channel
    00097  * configuration.
    00098  *
    00099  *  This type allows the device messaging APIs to handle a
    00100  *  protocol-specific configuration pointer opaquely until it is passed to
    00101  *  the specific protocol functions that use the data.
    00102  */
    00103 typedef void* dm_ChannelConfig_ptr;
    00104
    00105 /*! @brief This structure is a declaration of a channel descriptor type.
    00106  *  @details The channel descriptor contains the bus and protocol information required by the
    00107  *  device messaging functions to safely use a channel for communications. The
    00108  *  members are ordered to maintain natural alignment without inserting padding
    00109  *  bytes.
    00110  */
    00111 typedef struct dm_ChannelDescriptor_struct {
    00112     union {
    00113         i2c_BusHandle_t i2c;      /*!< The I2C channel handle.               */
    00114     } handle;                     /*!< The protocol-specific channel handle. */
    00115     const protocol_t * pProtocol; /*!< The pointer to protocol-specific functions and properties. */
    00116
    00117 } dm_ChannelDescriptor_t;
    00118
    00119 /*! @brief This structure defines a handle for the device.
    00120  *  @details The device handle contains the information required by the device
    00121  *  messaging functions to address and communicate with a slave device.
    00122  */
    00123 typedef struct dm_DeviceHandle_struct {
    00124     dm_ChannelDescriptor_t * pChannelDescriptor; /*!< The pointer to the channel descriptor. */
    00125     union {
    00126         i2c_SlaveHandle_t i2c;    /*!< The I2C device handle.               */
    00127     } handle;                     /*!< The protocol-specific device handle. */
    00128 } dm_DeviceHandle_t;
    00129
    00130 /*********************
    00131 ** Function Prototypes
    00132 */
    00133
    00134 /**
    00135  * @name Initialization Routines
    00136  * @{ */
    00137
    00138 /*! @brief       This function initializes a channel.
    00139  *
    00140  *  @details     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
    00141  *               during the initialization.
    00142  *
    00143  *  @param[in]   aChannelId     The ID of the channel to initialize. This is an index into the array of known channels that can be used.
    00144  *  @param[out]  apChannelDescriptor  The address of the channel descriptor structure to be initialized.
    00145  *
    00146  *  @return      ::dm_channel_init() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00147  *  @retval      ::ISF_SUCCESS       is returned when the channel initialized successfully and the apChannelDescriptor structure reference has been
    00148  *               populated with initialized channel data.
    00149  *  @retval      ::COMM_ERROR_NOEXIST  is returned when the supplied channel identifier does not exist.
    00150  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00151  *  @retval      ::COMM_ERROR_INIT     is returned when the channel could not be initialized.
    00152  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00153  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00154  *
    00155  *  @Constraints The following constraints must be observed when using this function:
    00156  *               @li aChannelId must be in the range of the known channel identifiers as defined in isf_sysconf_comms.h
    00157  *
    00158  *  @Reentrant   Yes
    00159  *  @Libs        isf_core.lib
    00160   */
    00161 isf_status_t dm_channel_init(
    00162     dm_ChannelId_t           aChannelId,
    00163     dm_ChannelDescriptor_t  *apChannelDescriptor
    00164 );
    00165
    00166 /*! @brief       This function reconfigures an already initialized channel.
    00167  *
    00168  *  @details     A channel may be reconfigured after initialization. Calls to dm_channel_configure() after initialization will override any previous
    00169  *               configuration values and must be made while the channel state is ::COMM_STATE_STOPPED.  The typical usage involves retrieving the
    00170  *               current configuration using ::dm_channel_get_config(), making modifications to the returned configuration, and then calling
    00171  *               dm_channel_configure() with the updated configuration. The channel is implicitly locked during the configuration.
    00172  *
    00173  *  @param[in]   apChannelDescriptor   The handle of the channel to be configured.
    00174  *  @param[in]   aChannelConfig        The channel configuration used during initialization.
    00175  *
    00176  *  @return      ::dm_channel_configure() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00177  *  @retval      ::ISF_SUCCESS        is returned when the channel was reconfigured successfully.
    00178  *  @retval      ::COMM_ERROR_STOP     is returned when the channel was not STOPPED.
    00179  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00180  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00181  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00182  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00183  *
    00184  *  @Constraints The following constraints must be observed when using this function:
    00185  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created
    00186  *                   when the ::dm_channel_init() function call is successfully returned.
    00187  *
    00188  *  @Reentrant   Yes
    00189  *  @Libs        isf_core.lib
    00190  */
    00191 isf_status_t dm_channel_configure(
    00192     dm_ChannelDescriptor_t  *apChannelDescriptor,
    00193     dm_ChannelConfig_ptr     aChannelConfig
    00194 );
    00195
    00196 /**  @} */
    00197
    00198 /**
    00199  * @name Queries and Status
    00200  * @{ */
    00201
    00202 /*! @brief       This function returns the channel state.
    00203  *
    00204  *  @details     A channel may be queried for its current state.
    00205  *
    00206  *  @param[in]   apChannelDescriptor   The handle of the channel to be queried.
    00207  *
    00208  *  @return      ::dm_channel_get_state() returns a value of type
    00209  *               ::comm_State_t indicating the current state of the channel.
    00210  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00211  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00212  *
    00213  *  @Constraints The following constraints must be observed when using this function:
    00214  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created when ::dm_channel_init() function call returns successfully.
    00215  *
    00216  *  @Reentrant   Yes
    00217  *  @Libs        isf_core.lib
    00218  */
    00219 comm_State_t dm_channel_get_state(dm_ChannelDescriptor_t *apChannelDescriptor);
    00220
    00221 /*! @brief       This function returns the current channel configuration.
    00222  *
    00223  *  @details     A channel may be queried for the current configuration.
    00224  *
    00225  *  @param[in]   apChannelDescriptor   The handle of the channel to be queried.
    00226  *  @param[out]  aChannelConfig        The address of a channel configuration to be filled.
    00227  *
    00228  *  @return      ::dm_channel_get_config() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00229  *  @retval      ::ISF_SUCCESS          is returned when the channel configuration is retrieved successfully.
    00230  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00231  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00232
    00233  *  @Constraints The following constraints must be observed when using this function:
    00234  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully.
    00235  *
    00236  *  @Reentrant   Yes
    00237  *  @Libs        isf_core.lib
    00238  */
    00239  isf_status_t dm_channel_get_config(
    00240     dm_ChannelDescriptor_t  *apChannelDescriptor,
    00241     dm_ChannelConfig_ptr     aChannelConfig
    00242  );
    00243
    00244 /**  @} */
    00245
    00246 /**
    00247  * @name Device Control Routines
    00248  * @{ */
    00249
    00250 /*! @brief       This function creates a device handle for a device at a specified channel address.
    00251  *
    00252  *   @details    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
    00253  *               during the open.
    00254  *
    00255  *  @param[in]   apChannelDescriptor   The handle of the channel to be queried.
    00256  *  @param[in]   aDeviceAddr           The known address of a device.
    00257  *  @param[out]  apDeviceHandle        The address of a DeviceHandle to be filled. ::dm_device_open() fills the provided device handle structure
    00258  *               with valid data when a device is found at the specified address.
    00259  *  @return      ::dm_channel_configure() returns a value of type ::isf_status_t indicating the success or failure of the function call.
    00260  *
    00261  *  @retval      ::ISF_SUCCESS        is returned when the device is located and a valid handle is returned.
    00262  *  @retval      ::COMM_ERROR_NOEXIST  is returned when a device does not exist at the specified address.
    00263  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00264  *  @retval      ::COMM_ERROR_STOP     is returned when the channel has not been started.
    00265  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00266  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00267  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00268  *
    00269  *  @Constraints The following constraints must be observed when using this function:
    00270  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created when the ::dm_channel_init() function call returns successfully.
    00271  *
    00272  *  @Reentrant   Yes
    00273  *  @Libs        isf_core.lib
    00274  */
    00275  isf_status_t dm_device_open(
    00276     dm_ChannelDescriptor_t  *apChannelDescriptor,
    00277     comm_Address_t           aDeviceAddr,
    00278     dm_DeviceHandle_t       *apDeviceHandle
    00279  );
    00280
    00281 /*! @brief       This function closes a device.
    00282  *
    00283  *  @details     The dm_device_close() function is used when no further communication with the device is needed. A closed device should not be
    00284  *               passed to ::dm_device_read() or ::dm_device_write(). The channel is implicitly locked during the close operation.
    00285  *
    00286  *  @param[in]   apDeviceHandle        The address of the DeviceHandle to be closed.
    00287  *  @return      ::dm_device_open() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00288  *  @retval      ::ISF_SUCCESS        is returned when the device changes to closed.
    00289  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00290  *
    00291  *  @Constraints The following constraints must be observed when using this function:
    00292  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function call returns successfully.
    00293  *
    00294  *  @Reentrant   Yes
    00295  *  @Libs        isf_core.lib
    00296  */
    00297  isf_status_t dm_device_close(
    00298     dm_DeviceHandle_t   *apDeviceHandle
    00299  );
    00300
    00301 /**  @} */
    00302
    00303 /**
    00304  * @name Channel Control Routines
    00305  * @{ */
    00306
    00307 /*! @brief       This function starts a channel.
    00308  *
    00309  *  @details     dm_channel_start() enables communications with an initialized channel.  This call enables the hardware peripherals
    00310  *               associated with the channel.  The channel is implicitly locked during the start operation.
    00311  *
    00312  *  @param[in]   apChannelDescriptor   The handle of the channel to be started.
    00313  *  @return      ::dm_channel_start() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00314  *  @retval      ::ISF_SUCCESS        is returned when the channel was started successfully.
    00315  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00316  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00317  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00318  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00319  *
    00320  *  @Constraints The following constraints must be observed when using this function:
    00321  *               @li apDeviceHandle must be valid. A valid device handle is created when the dm_device_open() function call returns successfully.
    00322  *
    00323  *  @Reentrant   Yes
    00324  *  @Libs        isf_core.lib
    00325  */
    00326 isf_status_t dm_channel_start(dm_ChannelDescriptor_t *apChannelDescriptor);
    00327
    00328 /*! @brief       This function stops a channel.
    00329  *
    00330  *  @details     dm_channel_stop() disables an initialized channel and stops communications with the channel.  This call disables the hardware peripherals
    00331  *               associated with the channel. The channel is implicitly locked during the stop operation.
    00332  *
    00333  *  @param[in]   apChannelDescriptor   The handle of the channel to be stopped.
    00334  *  @param[in]   aTimeout              The 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.
    00335  *  @return      ::dm_channel_stop() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00336  *
    00337  *  @retval      ::ISF_SUCCESS        is returned when the channel is successfully stopped.
    00338  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00339  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00340  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00341  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00342  *
    00343  *  @Constraints The following constraints must be observed when using this function:
    00344  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function call returns successfully.
    00345  *
    00346  *  @Reentrant   Yes
    00347  *  @Libs        isf_core.lib
    00348  */
    00349 isf_status_t dm_channel_stop(
    00350     dm_ChannelDescriptor_t *apChannelDescriptor,
    00351     isf_duration_t         aTimeout
    00352 );
    00353
    00354 /*! @brief       This function locks the channel for exclusive access.
    00355  *
    00356  *  @details     dm_channel_acquire_lock() serializes multi-client access. Each channel user must acquire a lock prior to sending
    00357  *               device messages. While holding the channel lock, no other clients may perform any channel operations. Therefore, it is important to release the lock
    00358  *               with ::dm_channel_release_lock() as soon as practical.
    00359  *
    00360  *  @param[in]   apChannelDescriptor   The handle of the channel to be started.
    00361  *  @param[in]   aTimeout              The 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
    00362  *               acquiring the lock, or wait as long as necessary for the lock to be acquired.
    00363  *  @return      ::dm_channel_acquire_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00364  *  @retval      ::ISF_SUCCESS        is returned when the channel lock is acquired.
    00365  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00366  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00367  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00368  *
    00369  *  @Constraints The following constraints must be observed when using this function:
    00370  *               @li The actual time spent in the call may be longer than the specified timeout due to the granularity of the timer used.
    00371  *               @li A valid device handle should be passed into the function.
    00372  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully.
    00373  *
    00374  *  @Reentrant   Yes
    00375  *  @Libs        isf_core.lib
    00376  */
    00377 isf_status_t dm_channel_acquire_lock(
    00378     dm_ChannelDescriptor_t *apChannelDescriptor,
    00379     isf_duration_t         aTimeout
    00380 );
    00381
    00382 /*! @brief       This function releases exclusive channel access.
    00383  *
    00384  *  @details     dm_channel_release_lock() is used to relinquish exclusive access on a paricular channel. It is the inverse of ::dm_channel_acquire_lock().
    00385  *
    00386  *  @param[in]   apChannelDescriptor   The handle of the channel to unlock.
    00387  *  @return      ::dm_channel_release_lock() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00388  *  @retval      ::ISF_SUCCESS        is returned when the channel released successfully.
    00389  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00390  *  @retval      ::COMM_ERROR_LOCK     is returned when no lock was held on the specified channel.
    00391  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00392  *
    00393  *  @Constraints The following constraints must be observed when using this function:
    00394  *               @li apChannelDescriptor must be valid. A valid channel descriptor is created when dm_channel_init() returns successfully.
    00395  *
    00396  *  @Reentrant   Yes
    00397  *  @Libs        isf_core.lib
    00398  */
    00399 isf_status_t dm_channel_release_lock(dm_ChannelDescriptor_t *apChannelDescriptor);
    00400
    00401 /**  @} */
    00402
    00403 /**
    00404  * @name Device Operation Routines
    00405  * @{ */
    00406
    00407 /*! @brief       This function reads from a device.
    00408  *
    00409  *  @details     dm_device_read() reads data from the specified device. The supplied command is sent to the device triggering the
    00410  *               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
    00411  *               does not trigger the device to return data, the dm_device_read() simply returns 0 bytes read.  The device is implicitly locked
    00412  *               during the read.
    00413  *
    00414  *  @param[in]   apDeviceHandle        The handle to the device from which to read.
    00415  *  @param[in]   apReadCmd             The read command to send to the device.
    00416  *  @param[in]   apReadBuffer          Buffer address where any returned data is placed.
    00417  *  @return      ::dm_device_read() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00418  *
    00419  *  @retval      ::ISF_SUCCESS        is returned when data from the device was read successfully.
    00420  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00421  *  @retval      ::COMM_ERROR_BUF_SIZE is returned when the provided buffer is too small to hold all the data or the number of bytes read is zero.
    00422  *  @retval      ::COMM_ERROR_STOP     is returned when the read is invoked on a stopped channel.
    00423  *  @retval      ::COMM_ERROR_NO_ACK   is returned when no acknowledgment was received from the device.
    00424  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00425  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00426  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00427  *  @retval      ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device.
    00428  *
    00429  *  @Constraints The following constraints must be observed when using this function:
    00430  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function returns successfully.
    00431  *
    00432  *  @Reentrant   Yes
    00433  *  @Libs        isf_core.lib
    00434  */
    00435 isf_status_t dm_device_read(
    00436     dm_DeviceHandle_t    *apDeviceHandle,
    00437     comm_Command_t       *apReadCmd,
    00438     comm_MessageBuffer_t *apReadBuffer
    00439 );
    00440
    00441 /*! @brief       This function reads from a device with extended behavior.
    00442  *
    00443  *  @details     dm_device_readx() reads data from the specified device. The supplied command is sent to the device which may trigger the device
    00444  *               to return some data.  Any data returned by the device is read and placed in the provided read buffer. dm_device_readx()
    00445  *               modifies the basic behavior of the read command by passing a set of bit flags to the underlying protocol interface.  To
    00446  *               successfully use the extended behavior, it is necessary to understand the underlying protocol being used and to pass the appropriate flag values.
    00447  *               The device is implicitly locked during the extension read.
    00448  *
    00449  *  @param[in]   apDeviceHandle        The handle to the device from which to read.
    00450  *  @param[in]   apReadCmd             The read command to transmit to the device.
    00451  *  @param[out]  apReadBuffer          Address of the buffer in which to place the read data.
    00452  *  @param[in]   aFlags                A set of bit flags controlling the behavior of the read.
    00453  *  @return      ::dm_device_readx() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00454  *  @retval      ::ISF_SUCCESS        is returned when the device was read successfully.
    00455  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00456  *  @retval      ::COMM_ERROR_BUF_SIZE The provided buffer is too small to hold all the data or the number of bytes to read is zero.
    00457  *  @retval      ::COMM_ERROR_STOP     is returned when the read is invoked on a stopped channel.
    00458  *  @retval      ::COMM_ERROR_NO_ACK   is returned when no acknowledgment was received from the device.
    00459  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00460  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00461  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00462  *  @retval      ::COMM_ERROR_DEV_CLOSED is returned when the read is invoked on a closed device.
    00463  *
    00464  *  @Constraints The following constraints must be observed when using this function:
    00465  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
    00466  *
    00467  *  @Reentrant   Yes
    00468  *  @Libs        isf_core.lib
    00469  */
    00470 isf_status_t dm_device_readx(
    00471     dm_DeviceHandle_t    *apDeviceHandle,
    00472     comm_Command_t       *apReadCmd,
    00473     comm_MessageBuffer_t *apReadBuffer,
    00474     comm_Flags_t          aFlags
    00475 );
    00476
    00477 /*! @brief       This function writes to a device.
    00478  *
    00479  *  @details     dm_device_write() writes data to the specified device. The device is implicitly locked during the write.
    00480  *
    00481  *  @param[in]   apDeviceHandle        The handle of the device to which to write.
    00482  *  @param[in]   apWriteCmd            The command to send to the device.
    00483  *  @return      ::dm_device_write() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00484  *  @retval      ::ISF_SUCCESS        is returned when the device was written successfully.
    00485  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00486  *  @retval      ::COMM_ERROR_STOP     is returned when the write is invoked on a stopped channel.
    00487  *  @retval      ::COMM_ERROR_NO_ACK   is returned when no acknowledgment was received from the device.
    00488  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00489  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00490  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00491  *  @retval      ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device.
    00492  *
    00493  *  @Constraints The following constraints must be observed when using this function:
    00494  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
    00495  *
    00496  *  @Reentrant   Yes
    00497  *  @Libs        isf_core.lib
    00498  */
    00499 isf_status_t dm_device_write(
    00500     dm_DeviceHandle_t *apDeviceHandle,
    00501     comm_Command_t    *apWriteCmd
    00502 );
    00503
    00504 /*! @brief       This function writes data to a device with extended write behavior.
    00505  *
    00506  *  @details     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
    00507  *               protocol interface. To successfully use the extended behavior, it is necessary to understand the underlying protocol used and to pass
    00508  *               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
    00509  *               flag values to explicitly control the RepeatedStart behavior at the conclusion of the ::dm_device_write() call.  The device is implicitly locked during
    00510  *               the extension write.
    00511  *
    00512  *  @param[in]   apDeviceHandle        The handle of the device to which to write.
    00513  *  @param[in]   apWriteCmd            The command to send to the device.
    00514  *  @param[in]   aFlags                A set of bit flags controlling the behavior of the write.
    00515  *  @return      ::dm_device_writex() returns a value of type ::isf_status_t indicating whether the operation was successful or unsuccessful.
    00516  *  @retval      ::ISF_SUCCESS        is returned when the data was successfully written to the device.
    00517  *  @retval      ::COMM_ERROR_INIT     is returned when the channel handle refers to a non-initialized channel.
    00518  *  @retval      ::COMM_ERROR_STOP     is returned when the write is invoked on a stopped channel.
    00519  *  @retval      ::COMM_ERROR_NO_ACK   is returned when no acknowledgment was received from the device.
    00520  *  @retval      ::COMM_ERROR_NULL_PTR is returned when a NULL pointer argument was passed into the function.
    00521  *  @retval      ::COMM_ERROR_TIME_OUT is returned when the request could not be fulfilled in the specified timeout period.
    00522  *  @retval      ::COMM_ERROR_LOCK     is returned when a lock could not be acquired properly.
    00523  *  @retval      ::COMM_ERROR_DEV_CLOSED is returned when the write is invoked on a closed device.
    00524  *
    00525  *  @Constraints The following constraints must be observed when using this function:
    00526  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() function returns successfully.
    00527  *
    00528  *  @Reentrant   Yes
    00529  *  @Libs        isf_core.lib
    00530  */
    00531 isf_status_t dm_device_writex(
    00532     dm_DeviceHandle_t  *apDeviceHandle,
    00533     comm_Command_t     *apWriteCmd,
    00534     comm_Flags_t        aFlags
    00535 );
    00536
    00537 /**  @} */
    00538
    00539 /*! @brief       This function retrieves the channel descriptor from a device handle.
    00540  *
    00541  *  @details     dm_channel_get_descriptor() returns the channel descriptor associated with the channel on which the device resides.
    00542  *
    00543  *  @param[in]   apDeviceHandle        Handle of device connected on the channel of interest.
    00544  *
    00545  *  @return      ::dm_channel_get_descriptor() returns a value of type ::dm_ChannelDescriptor_t which is pointer to an object.
    00546  *  @retval      NULL                 is returned when the specified device handle is invalid.
    00547  *
    00548  *  @Constraints None
    00549  *
    00550  *  @Constraints The following constraints must be observed when using this function:
    00551  *               @li apDeviceHandle must be valid. A valid device handle is created when the ::dm_device_open() returns successfully.
    00552  *
    00553  *  @Reentrant   Yes
    00554  *  @Libs        isf_core.lib
    00555  */
    00556 dm_ChannelDescriptor_t* dm_channel_get_descriptor(dm_DeviceHandle_t *apDeviceHandle);
    00557
    00558 #endif  /* INCLUDE_DEVICE_MESSAGING_H */
    00559