ISF  1.1
Intelligent Sensing Framework
 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