objacces.h

00001 /*
00002 This file is part of CanFestival, a library implementing CanOpen Stack. 
00003 
00004 Copyright (C): Edouard TISSERANT and Francis DUPIN
00005 
00006 See COPYING file for copyrights details.
00007 
00008 This library is free software; you can redistribute it and/or
00009 modify it under the terms of the GNU Lesser General Public
00010 License as published by the Free Software Foundation; either
00011 version 2.1 of the License, or (at your option) any later version.
00012 
00013 This library is distributed in the hope that it will be useful,
00014 but WITHOUT ANY WARRANTY; without even the implied warranty of
00015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016 Lesser General Public License for more details.
00017 
00018 You should have received a copy of the GNU Lesser General Public
00019 License along with this library; if not, write to the Free Software
00020 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00021 */
00022 
00023 /** @file
00024  *  @brief Responsible for accessing the object dictionary.
00025  *
00026  *  This file contains functions for accessing the object dictionary and
00027  *  variables that are contained by the object dictionary.
00028  *  Accessing the object dictionary contains setting local variables
00029  *  as PDOs and accessing (read/write) all entries of the object dictionary
00030  *  @warning Only the basic entries of an object dictionary are included
00031  *           at the moment.
00032  */
00033 
00034 /** @defgroup od Object Dictionary Management
00035  *  @brief The Object Dictionary is the heart of each CANopen device containing all communication and application objects.
00036  *  @ingroup userapi
00037  */
00038  
00039 #ifndef __objacces_h__
00040 #define __objacces_h__
00041 
00042 #include <applicfg.h>
00043 
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049 
00050 typedef UNS32 (*valueRangeTest_t)(UNS8 typeValue, void *Value);
00051 typedef void (* storeODSubIndex_t)(CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
00052 void _storeODSubIndex (CO_Data* d, UNS16 wIndex, UNS8 bSubindex);
00053 
00054 /**
00055  * @brief Print MSG_WAR (s) if error to the access to the object dictionary occurs.
00056  * 
00057  * You must uncomment the lines in the file objaccess.c :\n
00058  * //#define DEBUG_CAN\n
00059  * //#define DEBUG_WAR_CONSOLE_ON\n
00060  * //#define DEBUG_ERR_CONSOLE_ON\n\n
00061  * Beware that sometimes, we force the sizeDataDict or sizeDataGiven to 0, when we wants to use
00062  * this function but we do not have the access to the right value. One example is
00063  * getSDOerror(). So do not take attention to these variables if they are null.
00064  * @param index
00065  * @param subIndex
00066  * @param sizeDataDict Size of the data defined in the dictionary
00067  * @param sizeDataGiven Size data given by the user.
00068  * @param code error code to print. (SDO abort code. See file def.h)
00069  * @return
00070  */ 
00071 UNS8 accessDictionaryError(UNS16 index, UNS8 subIndex, 
00072                UNS32 sizeDataDict, UNS32 sizeDataGiven, UNS32 code);
00073 
00074 
00075 /* _getODentry() Reads an entry from the object dictionary.\n
00076  * 
00077  *    use getODentry() macro to read from object and endianize
00078  *    use readLocalDict() macro to read from object and not endianize   
00079  *
00080  * @code
00081  * // Example usage:
00082  * UNS8  *pbData;
00083  * UNS8 length;
00084  * UNS32 returnValue;
00085  *
00086  * returnValue = getODentry( (UNS16)0x100B, (UNS8)1, 
00087  * (void * *)&pbData, (UNS8 *)&length );
00088  * if( returnValue != SUCCESSFUL )
00089  * {
00090  *     // error handling
00091  * }
00092  * @endcode 
00093  * @param *d Pointer to a CAN object data structure
00094  * @param wIndex The index in the object dictionary where you want to read
00095  *               an entry
00096  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00097  *                  used to tell you how many valid entries you can find
00098  *                  in this index. Look at the canopen standard for further
00099  *                  information
00100  * @param *pDestData Pointer to the pointer which points to the variable where
00101  *                   the value of this object dictionary entry should be copied
00102  * @param pExpectedSize This function writes the size of the copied value (in Byte)
00103  *                      into this variable.
00104  * @param *pDataType Pointer to the type of the data. See objdictdef.h
00105  * @param CheckAccess if other than 0, do not read if the data is Write Only
00106  *                    [Not used today. Put always 0].
00107  * @param Endianize  When not 0, data is endianized into network byte order
00108  *                   when 0, data is not endianized and copied in machine native
00109  *                   endianness 
00110  * @return 
00111  * - OD_SUCCESSFUL is returned upon success. 
00112  * - SDO abort code is returned if error occurs . (See file def.h)
00113  */
00114 UNS32 _getODentry( CO_Data* d,
00115                    UNS16 wIndex,
00116                    UNS8 bSubindex,
00117                    void * pDestData,
00118                    UNS32 * pExpectedSize,
00119                    UNS8 * pDataType,
00120                    UNS8 checkAccess,
00121                    UNS8 endianize);
00122 
00123 /** 
00124  * @ingroup od
00125  * @brief getODentry() to read from object and endianize
00126  * @param OD Pointer to a CAN object data structure
00127  * @param wIndex The index in the object dictionary where you want to read
00128  *                an entry
00129  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00130  *                  used to tell you how many valid entries you can find
00131  *                  in this index. Look at the canopen standard for further
00132  *                  information
00133  * @param *pDestData Pointer to the pointer which points to the variable where
00134  *                   the value of this object dictionary entry should be copied
00135  * @param pExpectedSize This function writes the size of the copied value (in Byte)
00136  *                      into this variable.
00137  * @param *pDataType Pointer to the type of the data. See objdictdef.h
00138  * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)
00139  * @param endianize  Set to 1 : endianized into network byte order 
00140  * @return 
00141  * - OD_SUCCESSFUL is returned upon success. 
00142  * - SDO abort code is returned if error occurs . (See file def.h)
00143  */
00144 #define getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
00145                   pDataType,  checkAccess)                         \
00146        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
00147                   pDataType,  checkAccess, 1)            
00148 
00149 /** 
00150  * @ingroup od
00151  * @brief readLocalDict() reads an entry from the object dictionary, but in 
00152  * contrast to getODentry(), readLocalDict() doesn't endianize entry and reads
00153  * entry in machine native endianness. 
00154  * @param OD Pointer to a CAN object data structure
00155  * @param wIndex The index in the object dictionary where you want to read
00156  *                an entry
00157  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00158  *                  used to tell you how many valid entries you can find
00159  *                  in this index. Look at the canopen standard for further
00160  *                  information
00161  * @param *pDestData Pointer to the pointer which points to the variable where
00162  *                   the value of this object dictionary entry should be copied
00163  * @param pExpectedSize This function writes the size of the copied value (in Byte)
00164  *                      into this variable.
00165  * @param *pDataType Pointer to the type of the data. See objdictdef.h
00166  * @param checkAccess if other than 0, do not read if the data is Write Only
00167  *                    [Not used today. Put always 0].
00168  * @param endianize Set to 0, data is not endianized and copied in machine native
00169  *                  endianness 
00170  * @return 
00171  * - OD_SUCCESSFUL is returned upon success. 
00172  * - SDO abort code is returned if error occurs . (See file def.h)
00173  */
00174 #define readLocalDict( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
00175                   pDataType,  checkAccess)                         \
00176        _getODentry( OD, wIndex, bSubindex, pDestData, pExpectedSize, \
00177                   pDataType,  checkAccess, 0)
00178 
00179 /* By this function you can write an entry into the object dictionary
00180  * @param *d Pointer to a CAN object data structure
00181  * @param wIndex The index in the object dictionary where you want to write
00182  *               an entry
00183  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00184  *                  used to tell you how many valid entries you can find
00185  *                  in this index. Look at the canopen standard for further
00186  *                  information
00187  * @param *pSourceData Pointer to the variable that holds the value that should
00188  *                     be copied into the object dictionary
00189  * @param *pExpectedSize The size of the value (in Byte).
00190  * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)
00191  * @param endianize When not 0, data is endianized into network byte order
00192  *                  when 0, data is not endianized and copied in machine native
00193  *                  endianness   
00194  * @return 
00195  * - OD_SUCCESSFUL is returned upon success. 
00196  * - SDO abort code is returned if error occurs . (See file def.h)
00197  */
00198 UNS32 _setODentry( CO_Data* d,
00199                    UNS16 wIndex,
00200                    UNS8 bSubindex,
00201                    void * pSourceData,
00202                    UNS32 * pExpectedSize,
00203                    UNS8 checkAccess,
00204                    UNS8 endianize);
00205 
00206 /**
00207  * @ingroup od
00208  * @brief setODentry converts SourceData from network byte order to machine native 
00209  * format, and writes that to OD.
00210  * @code
00211  * // Example usage:
00212  * UNS8 B;
00213  * B = 0xFF; // set transmission type
00214  *
00215  * retcode = setODentry( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );
00216  * @endcode
00217  * @param d Pointer to a CAN object data structure
00218  * @param wIndex The index in the object dictionary where you want to write
00219  *               an entry
00220  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00221  *                  used to tell you how many valid entries you can find
00222  *                  in this index. Look at the canopen standard for further
00223  *                  information
00224  * @param *pSourceData Pointer to the variable that holds the value that should
00225  *                     be copied into the object dictionary
00226  * @param *pExpectedSize The size of the value (in Byte).
00227  * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)
00228  * @param endianize Set to 1 : endianized into network byte order
00229  * @return 
00230  * - OD_SUCCESSFUL is returned upon success. 
00231  * - SDO abort code is returned if error occurs . (See file def.h)
00232  */
00233 #define setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \
00234                   checkAccess) \
00235        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, \
00236                   checkAccess, 1)
00237 
00238 /** @fn UNS32 writeLocalDict(d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess)
00239  * @ingroup od
00240  * @hideinitializer
00241  * @brief Writes machine native SourceData to OD.
00242  * @param d Pointer to a CAN object data structure
00243  * @param wIndex The index in the object dictionary where you want to write
00244  *               an entry
00245  * @param bSubindex The subindex of the Index. e.g. mostly subindex 0 is
00246  *                  used to tell you how many valid entries you can find
00247  *                  in this index. Look at the canopen standard for further
00248  *                  information
00249  * @param *pSourceData Pointer to the variable that holds the value that should
00250  *                     be copied into the object dictionary
00251  * @param *pExpectedSize The size of the value (in Byte).
00252  * @param checkAccess Flag that indicate if a check rights must be perfomed (0 : no , other than 0 : yes)
00253  * @param endianize Data is not endianized and copied in machine native endianness 
00254  * @return 
00255  * - OD_SUCCESSFUL is returned upon success. 
00256  * - SDO abort code is returned if error occurs . (See file def.h)
00257  * \n\n
00258  * @code
00259  * // Example usage:
00260  * UNS8 B;
00261  * B = 0xFF; // set transmission type
00262  *
00263  * retcode = writeLocalDict( (UNS16)0x1800, (UNS8)2, &B, sizeof(UNS8), 1 );
00264  * @endcode
00265  */
00266 #define writeLocalDict( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess) \
00267        _setODentry( d, wIndex, bSubindex, pSourceData, pExpectedSize, checkAccess, 0)
00268 
00269 
00270 
00271 /**
00272  * @brief Scan the index of object dictionary. Used only by setODentry and getODentry.
00273  * @param *d Pointer to a CAN object data structure
00274  * @param wIndex
00275  * @param *errorCode :  OD_SUCCESSFUL if index foundor SDO abort code. (See file def.h)
00276  * @param **Callback
00277  * @return NULL if index not found. Else : return the table part of the object dictionary.
00278  */
00279  const indextable * scanIndexOD (CO_Data* d, UNS16 wIndex, UNS32 *errorCode, ODCallback_t **Callback);
00280 
00281 UNS32 RegisterSetODentryCallBack(CO_Data* d, UNS16 wIndex, UNS8 bSubindex, ODCallback_t Callback);
00282 
00283 #ifdef __cplusplus
00284 }
00285 #endif
00286 
00287 #endif /* __objacces_h__ */