Enlightenment CVS committal

Author  : raster
Project : e17
Module  : libs/eet

Dir     : e17/libs/eet/src/lib


Modified Files:
        Eet.h 


Log Message:


more documentation

===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/eet/src/lib/Eet.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -3 -r1.10 -r1.11
--- Eet.h       7 Jul 2003 07:52:20 -0000       1.10
+++ Eet.h       27 Jul 2003 13:12:33 -0000      1.11
@@ -328,8 +328,10 @@
     * @param func_list_next The function to get the next list node.
     * @param func_list_append The function to append a member to a list.
     * @param func_list_data The function to get the data from a list node.
+    * @param func_list_free The function to free an entire linked list.
     * @param func_hash_foreach The function to iterate through all hash table entries.
     * @param func_hash_add The function to add a member to a hash table.
+    * @param func_hash_free The function to free an entire hash table.
     * @return A new empty data descriptor.
     * 
     * This function creates a new data descriptore and returns a handle to the
@@ -529,7 +531,7 @@
     * likes. Eet can handle members being added or deleted from the data in
     * storage and safely zero-fills unfilled members if they were not found
     * in the data. It checks sizes and headers whenever it reads data, allowing
-    * the programmer ot not worry about corrupt data.
+    * the programmer to not worry about corrupt data.
     * 
     * Once a data structure has been described by the programmer with the
     * fields they wish to save or load, storing or retrieving a data structure
@@ -555,25 +557,75 @@
    int   eet_data_write(Eet_File *ef, Eet_Data_Descriptor *edd, char *name, void 
*data, int compress);
    
    /**
-    * To be documented.
-    *
-    * FIXME: To be fixed.
+    * Decode a data structure from an arbitary location in memory.
+    * @param edd The data  descriptor to use when decoding.
+    * @param data_in The pointer to the data to decode into a struct.
+    * @param size_in The size of the data pointed to in bytes.
+    * @return NULL on failure, or a valid decoded struct pointer on success.
+    * 
+    * This function will decode a data structure that has been encoded using
+    * eet_data_descriptor_encode(), and return a data structure with all its
+    * elements filled out, if successful, or NULL on failure.
+    * 
+    * The data to be decoded is stored at the memory pointed to by @p data_in,
+    * and is described by the descriptor pointed to by @p edd. The data size is
+    * passed in as the value to @p size_in, ande must be greater than 0 to
+    * succeed.
+    * 
+    * This function is useful for decoding data structures delivered to the
+    * application by means other than an eet file, such as an IPC or socket
+    * connection, raw files, shared memory etc.
+    * 
+    * Please see eet_data_read() for more information.
     * 
     */   
    void *eet_data_descriptor_decode(Eet_Data_Descriptor *edd, void *data_in, int 
size_in);
    
    /**
-    * To be documented.
+    * Encode a dsata struct to memory and return that encoded data.
+    * @param edd The data  descriptor to use when encoding.
+    * @param data_in The pointer to the struct to encode into data.
+    * @param size_ret A pointer to the an int to be filled with the decoded size.
+    * @return NULL on failure, or a valid encoded data chunk on success.
     *
-    * FIXME: To be fixed.
+    * This function takes a data structutre in memory and encodes it into a
+    * serialised chunk of data that can be decoded again by 
+    * eet_data_descriptor_decode(). This is useful for being able to transmit
+    * data structures across sockets, pipes, IPC or shared file mechanisms,
+    * without having to worry about memory space, machine type, endianess etc.
+    * 
+    * The parameter @p edd must point to a valid data descriptor, and
+    * @p data_in must point to the right data structure to encode. If not, the
+    * encoding may fail.
+    * 
+    * On success a non NULL valid pointer is returned and what @p size_ret
+    * points to is set to the size of this decoded data, in bytes. When the
+    * encoded data is no longer needed, call free() on it. On failure NULL is
+    * returned and what @p size_ret points to is set to 0.
+    * 
+    * Please see eet_data_write() for more information.
     * 
     */
    void *eet_data_descriptor_encode(Eet_Data_Descriptor *edd, void *data_in, int 
*size_ret);
 
    /**
-    * To be documented.
-    *
-    * FIXME: To be fixed.
+    * Add a basic data element to a data descriptor.
+    * @param edd The data descriptor to add the type to.
+    * @param struct_type The type of the struct.
+    * @param name The string name to use to encode/decode this member.
+    * @param member The struct member itself to be encoded.
+    * @param type The type of the member to encode.
+    * 
+    * This macro is a convenience macro provided to add a member to the data
+    * descriptor @p edd. The type of the structure is provided as the
+    * @p struct_type parameter (for example: struct my_struct). The @p name
+    * parameter defines a string that will be used to uniquely name that
+    * member of the struct (it is suggested to use the struct member itself).
+    * The @p member parameter is the actual struct member itself (for
+    * example: values), and @p type is the basic data type of the member which
+    * must be one of: EET_T_CHAR, EET_T_SHORT, EET_T_INT, EET_T_LONG_LONG,
+    * EET_T_FLOAT, EET_T_DOUBLE, EET_T_UCHAR, EET_T_USHORT, EET_T_UINT,
+    * EET_T_ULONG_LONG or EET_T_STRING.
     * 
     */
 #define EET_DATA_DESCRIPTOR_ADD_BASIC(edd, struct_type, name, member, type) \
@@ -586,9 +638,18 @@
      }
    
    /**
-    * To be documented.
-    *
-    * FIXME: To be fixed.
+    * Add a sub-element type to a data descriptor
+    * @param edd The data descriptor to add the type to.
+    * @param struct_type The type of the struct.
+    * @param name The string name to use to encode/decode this member.
+    * @param member The struct member itself to be encoded.
+    * @param subtype The type of sub-type struct to add.
+    * 
+    * This macro lets you easily add a sub-type (a struct that's pointed to
+    * by this one). All the parameters are the same as for 
+    * EET_DATA_DESCRIPTOR_ADD_BASIC(), with the @p subtype being the exception.
+    * This must be the data descriptor of the struct that is pointed to by
+    * this element.
     * 
     */
 #define EET_DATA_DESCRIPTOR_ADD_SUB(edd, struct_type, name, member, subtype) \
@@ -601,9 +662,17 @@
      }
    
    /**
-    * To be documented.
-    *
-    * FIXME: To be fixed.
+    * Add a linked list type to a data descriptor
+    * @param edd The data descriptor to add the type to.
+    * @param struct_type The type of the struct.
+    * @param name The string name to use to encode/decode this member.
+    * @param member The struct member itself to be encoded.
+    * @param subtype The type of linked list member to add.
+    * 
+    * This macro lets you easily add a linked list of other data types. All the 
+    * parameters are the same as for EET_DATA_DESCRIPTOR_ADD_BASIC(), with the 
+    * @p subtype being the exception. This must be the data descriptor of the
+    * element that is in each member of the linked list to be stored.
     * 
     */
 #define EET_DATA_DESCRIPTOR_ADD_LIST(edd, struct_type, name, member, subtype) \




-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100003ave/direct;at.aspnet_072303_01/01
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs

Reply via email to