Mercurial Mercurial > canfestival / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
include/sdo.h
changeset 561 f9be4262c68d
parent 539 187058b4a4b8
child 636 033fe6f1ec3c 
--- a/include/sdo.h	Wed Jul 15 17:19:09 2009 +0200
+++ b/include/sdo.h	Thu Jul 16 10:06:57 2009 +0200
@@ -188,7 +188,6 @@
  * to store a new SDO.
  * ie a line which value of the field "state" is "SDO_RESET"
  * An unused line have the field "state" at the value SDO_RESET
- * bus_id is hardware dependant
  * @param *d Pointer on a CAN object data structure
  * @param whoami Create the line for a SDO_SERVER or SDO_CLIENT.
  * @param *line Pointer on a SDO line 
@@ -199,7 +198,6 @@
 /** 
  * @brief Search for the line, in the transfers array, which contains the
  * beginning of the reception of a fragmented SDO
- * bus_id is hardware dependant
  * @param *d Pointer on a CAN object data structure
  * @param nodeId correspond to the message node-id
  * @param whoami takes 2 values : look for a line opened as SDO_CLIENT or SDO_SERVER
@@ -218,7 +216,6 @@
 
 /** 
  * @brief Bytes in the line structure which must be transmited (or received)
- * bus_id is hardware dependant.
  * @param *d Pointer on a CAN object data structure
  * @param line SDO line 
  * @param *nbBytes Pointer on nbBytes
@@ -228,7 +225,6 @@
 
 /** 
  * @brief Store in the line structure the nb of bytes which must be transmited (or received)
- * bus_id is hardware dependant.
  * @param *d Pointer on a CAN object data structure
  * @param line SDO line 
  * @param nbBytes
@@ -238,7 +234,6 @@
 
 /**
  * @brief Transmit a SDO frame on the bus bus_id
- * bus_id is hardware dependant
  * @param *d Pointer on a CAN object data structure
  * @param whoami Takes 2 values : SDO_CLIENT or SDO_SERVER
  * @param sdo SDO Structure which contains the sdo to transmit
@@ -264,7 +259,6 @@
 
 /** 
  * @brief Treat a SDO frame reception
- * bus_id is hardware dependant
  * call the function sendSDO
  * @param *d Pointer on a CAN object data structure
  * @param *m Pointer on a CAN message structure 
@@ -277,17 +271,18 @@
 
 /** 
  * @ingroup sdo
- * @brief Used by the application to send a SDO request frame to write the data *data
- * at the index and subIndex indicated
- * bus_id is hardware dependant
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
+ * @brief Used to send a SDO request frame to write the data at the index and subIndex indicated
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
  * @param index At index indicated
  * @param subIndex At subIndex indicated
  * @param count number of bytes to write in the dictionnary.
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
- * @param *data Pointer on data
- * @return 0xFF if error, else return 0
+ * @param *data Pointer to data
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFE is returned when no sdo client to communicate with node.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 writeNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index,
 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data);
@@ -295,17 +290,20 @@
 /** 
  * @ingroup sdo
  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
- * The function Callback which must be defined in the user code is called at the
+ * @details The function Callback which must be defined in the user code is called at the
  * end of the exchange. (on succes or abort).
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
  * @param index At index indicated
  * @param subIndex At subIndex indicated
  * @param count number of bytes to write in the dictionnary.
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
- * @param *data Pointer on data
+ * @param *data Pointer to data
  * @param Callback Callback function
- * @return 0xFF if error, else return 0
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFE is returned when no sdo client to communicate with node.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 writeNetworkDictCallBack (CO_Data* d, UNS8 nodeId, UNS16 index,
 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback);
@@ -313,115 +311,130 @@
 /**
  * @ingroup sdo 
  * @brief Used to send a SDO request frame to write in a distant node dictionnary.
- * The function Callback	which must be defined in the user code is called at the
+ * @details The function Callback which must be defined in the user code is called at the
  * end of the exchange. (on succes or abort). First free SDO client parameter is
  * automatically initialized for specific node if not already defined.
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
  * @param index At index indicated
  * @param subIndex At subIndex indicated
  * @param count number of bytes to write in the dictionnary.
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
- * @param *data Pointer on data
+ * @param *data Pointer to data
  * @param Callback Callback function
  * @param endianize When not 0, data is endianized into network byte order
  *                  when 0, data is not endianized and copied in machine native
  *                  endianness
- * @return 0xFF if error, else return 0
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 writeNetworkDictCallBackAI (CO_Data* d, UNS8 nodeId, UNS16 index,
 		       UNS8 subIndex, UNS32 count, UNS8 dataType, void *data, SDOCallback_t Callback, UNS8 endianize);
 
 /**
  * @ingroup sdo 
- * @brief Used by the application to send a SDO request frame to read
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
- * @param index At index indicated
- * @param subIndex At subIndex indicated
- * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value. * bus_id is hardware dependant
- * @return 0xFF if error, else return 0
+ * @brief Used to send a SDO request frame to read.
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
+ * @param index At index indicated
+ * @param subIndex At subIndex indicated
+ * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFE is returned when no sdo client to communicate with node.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 readNetworkDict (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType);
 
 /** 
  * @ingroup sdo
  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
- * The function Callback which must be defined in the user code is called at the
+ * @details The function Callback which must be defined in the user code is called at the
  * end of the exchange. (on succes or abort).
  * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
+ * @param nodeId Node Id of the slave
  * @param index At index indicated
  * @param subIndex At subIndex indicated
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
  * @param Callback Callback function
- * @return 0xFF if error, else return 0
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFE is returned when no sdo client to communicate with node.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 readNetworkDictCallback (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
 
 /** 
  * @ingroup sdo
  * @brief Used to send a SDO request frame to read in a distant node dictionnary.
- * The function Callback which must be defined in the user code is called at the
+ * @details The function Callback which must be defined in the user code is called at the
  * end of the exchange. (on succes or abort). First free SDO client parameter is
  * automatically initialized for specific node if not already defined.
  * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
+ * @param nodeId Node Id of the slave
  * @param index At index indicated
  * @param subIndex At subIndex indicated
  * @param dataType (defined in objdictdef.h) : put "visible_string" for strings, 0 for integers or reals or other value.
  * @param Callback Callback function
- * @return 0xFF if error, else return 0
+ * @return 
+ * - 0 is returned upon success.
+ * - 0xFF is returned when error occurs.
  */
 UNS8 readNetworkDictCallbackAI (CO_Data* d, UNS8 nodeId, UNS16 index, UNS8 subIndex, UNS8 dataType, SDOCallback_t Callback);
 
 /** 
  * @ingroup sdo
- * @brief Use this function after a readNetworkDict to get the result.
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
- * @param *data Pointer on data
- * @param *size Pointer on size
- * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
+ * @brief Use this function after calling readNetworkDict to get the result.
+ * 
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
+ * @param *data Pointer to the datas
+ * @param *size Pointer to the size
+ * @param *abortCode Pointer to the abortcode. (0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
  * 
  * 
  * @return
- *           - SDO_FINISHED             // data is available
- *           - SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
- *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
- *           - SDO_UPLOAD_IN_PROGRESS   // Data not yet available
- *           - SDO_DOWNLOAD_IN_PROGRESS // Should not arrive !
+ *           - SDO_FINISHED             // datas are available
+ *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
+ *           - SDO_ABORTED_INTERNAL     // Transfert failed (internal abort)
+ *           - SDO_UPLOAD_IN_PROGRESS   // Datas are not yet available
+ *           - SDO_DOWNLOAD_IN_PROGRESS // Download is in progress
+ * \n\n
+ * example :
  * @code
- * example :
  * UNS32 data;
  * UNS8 size;
  * readNetworkDict(0, 0x05, 0x1016, 1, 0) // get the data index 1016 subindex 1 of node 5
- * while (getReadResultNetworkDict (0, 0x05, &data, &size) != SDO_UPLOAD_IN_PROGRESS);
+ * while (getReadResultNetworkDict (0, 0x05, &data, &size) == SDO_UPLOAD_IN_PROGRESS);
  * @endcode
 */
 UNS8 getReadResultNetworkDict (CO_Data* d, UNS8 nodeId, void* data, UNS32 *size, UNS32 * abortCode);
 
 /**
- * @brief Use this function after a writeNetworkDict to get the result of the write
- * It is mandatory to call this function because it is releasing the line used for the transfer.
- * @param *d Pointer on a CAN object data structure
- * @param nodeId In the dictionary of the slave whose node_id is nodeId
- * @param *abortCode Pointer on the abortcode. 0 = not available. Else : SDO abort code. (received if return SDO_ABORTED_RCV)
+ * @ingroup sdo
+ * @brief Use this function after calling writeNetworkDict function to get the result of the write.
+ * @details It is mandatory to call this function because it is releasing the line used for the transfer.
+ * @param *d Pointer to a CAN object data structure
+ * @param nodeId Node Id of the slave
+ * @param *abortCode Pointer to the abortcode
+ * - 0 = not available. 
+ * - SDO abort code (received if return SDO_ABORTED_RCV)
  * 
  * @return : 
- *           - SDO_FINISHED             // data is available
- *           - SDO_ABORTED_RCV          // Transfert failed. (abort SDO received)
- *           - SDO_ABORTED_INTERNAL     // Transfert failed. Internal abort.
- *           - SDO_DOWNLOAD_IN_PROGRESS // Data not yet available
- *           - SDO_UPLOAD_IN_PROGRESS   // Should not arrive !
- * 
+ *           - SDO_FINISHED             // datas are available
+ *           - SDO_ABORTED_RCV          // Transfert failed (abort SDO received)
+ *           - SDO_ABORTED_INTERNAL     // Transfert failed (Internal abort)
+ *           - SDO_DOWNLOAD_IN_PROGRESS // Datas are not yet available
+ *           - SDO_UPLOAD_IN_PROGRESS   // Upload in progress
+ * \n\n
+ * example :
  * @code
- * example :
  * UNS32 data = 0x50;
  * UNS8 size;
  * UNS32 abortCode;
  * writeNetworkDict(0, 0x05, 0x1016, 1, size, &data) // write the data index 1016 subindex 1 of node 5
- * while (getWriteResultNetworkDict (0, 0x05, &abortCode) != SDO_DOWNLOAD_IN_PROGRESS);
+ * while (getWriteResultNetworkDict (0, 0x05, &abortCode) == SDO_DOWNLOAD_IN_PROGRESS);
  * @endcode
 */
 UNS8 getWriteResultNetworkDict (CO_Data* d, UNS8 nodeId, UNS32 * abortCode);
canfestival