Enlightenment CVS committal
Author : mej
Project : eterm
Module : libast
Dir : eterm/libast/include/libast
Modified Files:
obj.h types.h.in
Log Message:
Tue Jul 1 15:50:57 2003 Michael Jennings (mej)
Finished the type docs. Still working on the object docs.
===================================================================
RCS file: /cvsroot/enlightenment/eterm/libast/include/libast/obj.h,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -3 -r1.15 -r1.16
--- obj.h 27 Jun 2003 21:53:49 -0000 1.15
+++ obj.h 1 Jul 2003 19:51:21 -0000 1.16
@@ -71,7 +71,7 @@
* @param t The object type as a non-quoted string (e.g., obj).
* @return An appropriate @c typedef and @c struct introducer.
*
- * @see DOXGRP_OBJ
+ * @see DOXGRP_OBJ, SPIF_DEFINE_TYPE(), SPIF_DECL_OBJ_STRUCT()
*/
#define SPIF_DEFINE_OBJ(t) SPIF_DEFINE_TYPE(t,
SPIF_DECL_OBJ_STRUCT(t)); SPIF_DECL_OBJ_STRUCT(t)
/**
@@ -89,11 +89,44 @@
*
* @param t The object type as a non-quoted string (e.g., obj).
*
- * @see DOXGRP_OBJ
+ * @see DOXGRP_OBJ, SPIF_CONST_TYPE()
*/
#define SPIF_DECL_PARENT_TYPE(t) SPIF_CONST_TYPE(t) parent
/**
+ * Declare the class variable for objects of a given type.
+ *
+ * Every object type has a class variable which is declared using this
+ * macro. Any instance of that type of object contains a pointer to
+ * this same class variable. This class variable is both declared and
+ * referenced using this macro so that its actual name is abstracted.
+ *
+ * @param type The object type as a non-quoted string (e.g., obj).
+ * @return The class variable for the given type.
+ *
+ * @see DOXGRP_OBJ
+ */
+#define SPIF_CLASS_VAR(type) spif_ ## type ## _class
+/[EMAIL PROTECTED]/
+
+/[EMAIL PROTECTED]/
+/**
+ * @name Generic Object/Class Casting Macros
+ * Macros used to typecast arbitrary objects to generic types.
+ *
+ * This set of macros allows objects of any type (i.e., any object
+ * descended from the basic "obj" or "class" type) to be treated as
+ * generic object/class variables. In other words, as long as an
+ * object is properly defined (i.e., properly descended from its basic
+ * type), it can be treated as that basic type via use of these
+ * macros. The end result is that any operation which is defined for
+ * all objects can be executed on an object of any type without the
+ * need to know its exact type.
+ *
+ * @ingroup DOXGRP_OBJ
+ */
+
+/**
* Cast an arbitrary class object to the generic class type.
*
* Most non-interface classes use the generic obj-style class
@@ -108,7 +141,7 @@
* @param cls An arbitrary class object.
* @return The class object cast to the generic type.
*
- * @see DOXGRP_OBJ, SPIF_OBJ_CLASS()
+ * @see DOXGRP_OBJ, SPIF_OBJ_CLASS(), SPIF_CAST()
*/
#define SPIF_CLASS(cls) (SPIF_CAST(class) (cls))
@@ -121,12 +154,48 @@
* @param cls An arbitrary class object.
* @return The class object cast to the generic type.
*
- * @see DOXGRP_OBJ, SPIF_CLASS()
+ * @see DOXGRP_OBJ, SPIF_CLASS(), SPIF_CONST_CAST()
*/
#define SPIF_CONST_CLASS(cls) (SPIF_CONST_CAST(class) (cls))
-/* Assembles the name of the object class variable. */
-#define SPIF_CLASS_VAR(type) spif_ ## type ## _class
+/* FIXME: Do we need the nullobj stuff? I don't think so. */
+/* UNDOCUMENTED */
+#define SPIF_NULLOBJ(obj) (SPIF_CAST(nullobj) (obj))
+
+/**
+ * Cast an arbitrary object to an obj.
+ *
+ * This macro allows an arbitrary object of any valid object type
+ * (i.e., anything derived from spif_obj_t) to be treated as a generic
+ * object (the spif_obj_t type). Any method defined for generic
+ * objects (i.e., all objects) can be called on any object using a
+ * typecast such as this, and any function or macro which needs an
+ * arbitrary object can be passed any object using this macro.
+ *
+ * @param obj An object of any valid type.
+ * @return A generic object reference to that object.
+ *
+ * @see DOXGRP_OBJ, SPIF_CAST()
+ */
+#define SPIF_OBJ(obj) (SPIF_CAST(obj) (obj))
+/[EMAIL PROTECTED]/
+
+/[EMAIL PROTECTED]/
+/**
+ * @name Generic Object Type Safety Macros
+ * Macros used to test, determine, and/or verify an object's type.
+ *
+ * Macros in this group are used to verify the validity of an object
+ * instance and its type.
+ *
+ * @ingroup DOXGRP_OBJ
+ */
+
+/* Check to see if a pointer references an obj. */
+#define SPIF_OBJ_IS_OBJ(o) (SPIF_OBJ_IS_TYPE(o, obj))
+
+/* Used for testing the NULL-ness of objects. */
+#define SPIF_OBJ_ISNULL(o) (SPIF_OBJ(o) == SPIF_NULL_TYPE(obj))
/* Check to see if a pointer references an object. Increasing levels
of accuracy at the expense of some speed for the higher debug levels.
@@ -139,20 +208,18 @@
#else
# define SPIF_OBJ_CHECK_TYPE(o, type) SPIF_OBJ_IS_TYPE(o, type)
#endif
+/[EMAIL PROTECTED]/
-/* Cast an arbitrary object pointer to a pointer to a nullobj. Coincidentally,
- a nullobj *is* an arbitrary object pointer. Even moreso than an obj. :-) */
-#define SPIF_NULLOBJ(obj) ((spif_nullobj_t) (obj))
-
-/* Cast an arbitrary object pointer to an obj. Any object of sufficient size
- and/or complexity should be derived from this type. */
-#define SPIF_OBJ(obj) ((spif_obj_t) (obj))
-
-/* Check to see if a pointer references an obj. */
-#define SPIF_OBJ_IS_OBJ(o) (SPIF_OBJ_IS_TYPE(o, obj))
-
-/* Used for testing the NULL-ness of objects. */
-#define SPIF_OBJ_ISNULL(o) (SPIF_OBJ(o) == SPIF_NULL_TYPE(obj))
+/[EMAIL PROTECTED]/
+/**
+ * @name Generic Object Instance Macros
+ * Macros used to operate on generic objects.
+ *
+ * This set of macros manipulates actual object instances in various
+ * ways.
+ *
+ * @ingroup DOXGRP_OBJ
+ */
/* Access the implementation class member of an object. */
#define SPIF_OBJ_CLASS(obj) (SPIF_CLASS(SPIF_OBJ(obj)->cls))
===================================================================
RCS file: /cvsroot/enlightenment/eterm/libast/include/libast/types.h.in,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -3 -r1.8 -r1.9
--- types.h.in 19 Feb 2003 21:10:30 -0000 1.8
+++ types.h.in 1 Jul 2003 19:51:21 -0000 1.9
@@ -21,92 +21,785 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+/**
+ * @file types.h
+ * LibAST Portable Data Types
+ *
+ * This file contains a collection of well-defined data types and the
+ * tools for manipulating them.
+ *
+ * @author Michael Jennings <[EMAIL PROTECTED]>
+ * $Revision: 1.8 $
+ * $Date: 2003/06/17 00:44:08 $
+ */
+
#ifndef _LIBAST_TYPES_H_
#define _LIBAST_TYPES_H_
-/* Macros to construct object types from the basenames of the types (obj, str, etc.)
*/
+
+/**
+ * @defgroup DOXGRP_TYPES LibAST Portable Data Types
+ *
+ * A collection of well-defined data types and the tools for
+ * manipulating them.
+ *
+ * As any C programmer who cares about portability knows, dealing with
+ * different types on different platforms can be a problem. On some
+ * platforms, int is 16-bit and long is 32-bit; on others, both int
+ * and long are 32-bit and there is no long long; others have long
+ * long as a 64-bit integer; and then there are the native 64-bit
+ * platforms where long can also be 64-bit. Not to mention the
+ * presence/absence of boolean types/defines, signed vs. unsigned
+ * char, and so forth.
+ *
+ * LibAST solves this problem by defining data types for specific
+ * integer sizes that are guaranteed to be defined on any system with
+ * LibAST. Also, the basic data types are given their own new data
+ * types which make signedness vs. unsignedness specifically stated,
+ * preventing bad assumptions.
+ *
+ * Also included are macros for building LibAST type names from their
+ * basenames, allocating LibAST objects, typecasting, generating
+ * type-specific NULL comparisons, stringizing NULL values, taking the
+ * size of a LibAST object type, and more.
+ *
+ * There are a few potential gotchas here, so please read the
+ * following documentation carefully for each part you wish to use.
+ */
+
+/[EMAIL PROTECTED]/
+/**
+ * @name Type Name Composition Macros
+ * ---
+ *
+ * These macros convert basenames like "obj" into actual typenames
+ * like "spif_obj_t." This is primarily intended for use by other
+ * macros and in places where the basename of the type should be
+ * emphasized.
+ *
+ * @note LibAST's use of the term "const type" does @em NOT match the
+ * traditional C definition of the term @c const. When you declare a
+ * variable of a type like @c spif_obj_t or @c SPIF_TYPE(obj), you are
+ * actually defining a pointer variable which will point to an object
+ * of that type. Why a pointer? Because they're the closest thing C
+ * has to references. However, in places where the actual structure
+ * is needed as opposed to to a pointer (like when using sizeof()),
+ * the @c CONST version of the macro should be used instead.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * Create a complete type name from its basename.
+ *
+ * This macro converts a basename (such as "obj" or "charptr" or
+ * "uint8") into a namespace-safe full type name.
+ *
+ * @param type The type basename.
+ * @return The full type name.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_TYPE(type) spif_ ## type ## _t
+
+/**
+ * Create a complete const type name from its basename.
+ *
+ * This macro converts a basename (such as "obj" or "charptr" or
+ * "uint8") into a namespace-safe const type name.
+ *
+ * @param type The type basename.
+ * @return The full const type name.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_CONST_TYPE(type) spif_const_ ## type ## _t
-/* Macros to allocate and deallocate memory for an object. For use only in
- object constructors/destructors, not in end-user programs. */
+/**
+ * Obtain the size of a type from its basename.
+ *
+ * This macro returns the size of the given type basename (such as
+ * "obj" or "charptr" or "uint8"). This is primarily used for objects
+ * and other structures whose types are actually struct pointers.
+ *
+ * @param type The type basename.
+ * @return The size of objects/structures of that type.
+ *
+ * @see DOXGRP_TYPES
+ */
+#define SPIF_SIZEOF_TYPE(type) (sizeof(SPIF_CONST_TYPE(type)))
+
+/**
+ * Define a type and its corresponding const type.
+ *
+ * This macro creates a typedef which maps the const type @a t to the
+ * type specified by @a u and a typedef which maps the type @a t to a
+ * pointer to its const type. Again, this is used for structures.
+ *
+ * @param t The type basename.
+ * @param u The actual type it's being mapped to.
+ *
+ * @see DOXGRP_TYPES
+ */
+#define SPIF_DEFINE_TYPE(t, u) typedef u SPIF_CONST_TYPE(t); typedef
SPIF_CONST_TYPE(t) * SPIF_TYPE(t)
+/[EMAIL PROTECTED]/
+
+/[EMAIL PROTECTED]/
+/**
+ * @name Object-Specific Macros
+ * ---
+ *
+ * These macros are intended for use specifically with objects.
+ *
+ * @see DOXGRP_OBJ
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * Allocate an object (or other structured type) by its basename.
+ *
+ * This macro is used primarily in object constructors. It allocates
+ * and returns the specified type.
+ *
+ * @param type The type basename.
+ * @return An allocated object of the specified type.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_ALLOC(type) SPIF_CAST(type)
MALLOC(SPIF_SIZEOF_TYPE(type))
+
+/**
+ * Deallocate an object (or other structured type).
+ *
+ * This macro is used primarily in object destructors. It frees the
+ * memory associated with the specified object and invalidates it.
+ *
+ * @param obj The object to be freed.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_DEALLOC(obj) FREE(obj)
-/* Macros for specifying the classname variables for each class type. Each subclass
of
- spif_obj_t must define this variable using these macros. */
+/**
+ * Builds the classname variable for a particular base type.
+ *
+ * This macro converts a basename into the classname for that type.
+ * It is primarily used in initialization of class objects.
+ *
+ * @param type The type basename.
+ * @return A string representing the classname for that type.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_DECL_CLASSNAME(type) "!spif_" #type "_t!"
+/[EMAIL PROTECTED]/
-/* Typecast macros */
+/[EMAIL PROTECTED]/
+/**
+ * @name Typecast Macros
+ * ---
+ *
+ * These macros provide typecasting by basename for LibAST types.
+ * Cast macros are also provided for native C types to provide
+ * consistency of casting method.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * Typecast to a native C type.
+ *
+ * This macro is identical to traditional C typecasting and is
+ * supplied primarily for consistency.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_CAST_C(type) (type)
+
+/**
+ * Typecast to a const native C type.
+ *
+ * This macro is identical to traditional C typecasting, except that
+ * the @c const keyword is added to the typecast. It is supplied
+ * primarily for consistency.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_CONST_CAST_C(type) (const type)
+
+/**
+ * Typecast to a LibAST type by basename.
+ *
+ * This macro typecasts a value to a particular LibAST type by its
+ * basename. It is usually employed where emphasis on the basename is
+ * desired, particularly with objects.
+ *
+ * @see DOXGRP_TYPES, SPIF_TYPE()
+ */
#define SPIF_CAST(type) (SPIF_TYPE(type))
+
+/**
+ * Typecast to a const LibAST type by basename.
+ *
+ * This macro is identical to SPIF_CAST(), except that the @c const
+ * keyword is added to the typecast.
+ *
+ * @note DO NOT confuse this typecast with the "const type"
+ * terminology. This typecast applies const-ness (i.e., immutability)
+ * to an object or other value.
+ *
+ * @see DOXGRP_TYPES, SPIF_TYPE(), SPIF_CAST()
+ */
#define SPIF_CONST_CAST(type) (const SPIF_TYPE(type))
+
+/**
+ * Typecast to a pointer to a LibAST type by basename.
+ *
+ * This macro typecasts a value to a pointer to a particular LibAST
+ * type by its basename. It is usually employed where emphasis on the
+ * basename is desired, particularly with objects.
+ *
+ * @see DOXGRP_TYPES, SPIF_TYPE()
+ */
#define SPIF_CAST_PTR(type) (SPIF_TYPE(type) *)
+
+/**
+ * Typecast to a pointer to a const LibAST type by basename.
+ *
+ * This macro is identical to SPIF_CAST_PTR(), except that the @c
+ * const keyword is added to the typecast.
+ *
+ * @note DO NOT confuse this typecast with the "const type"
+ * terminology. This typecast applies const-ness (i.e., immutability)
+ * to the object or other value referenced by the pointer.
+ *
+ * @see DOXGRP_TYPES, SPIF_TYPE(), SPIF_CAST_PTR()
+ */
#define SPIF_CONST_CAST_PTR(type) (const SPIF_TYPE(type) *)
+/[EMAIL PROTECTED]/
-/* Cast the NULL pointer to a particular object type. */
+/[EMAIL PROTECTED]/
+/**
+ * @name NULL Handling Macros
+ * ---
+ *
+ * These macros handle typecasting the NULL pointer to a specific
+ * basename/type and printing out values which are set to NULL of a
+ * specific basename/type.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * Returns a NULL object of the specified base type.
+ *
+ * This macro returns a NULL object of the type specified by the given
+ * basename. It is generally used for initializing object member
+ * variables and for returning correctly-typed NULL objects.
+ *
+ * @param type The type basename.
+ * @return A NULL object of the specified type.
+ *
+ * @see DOXGRP_TYPES, SPIF_CAST()
+ */
#define SPIF_NULL_TYPE(type) (SPIF_CAST(type) (NULL))
+
+/**
+ * Returns a NULL object of the specified native C type.
+ *
+ * This macro returns a NULL object of the specified C type. It is
+ * included primarily for consistency.
+ *
+ * @param type The native C type.
+ * @return A NULL value of the specified type.
+ *
+ * @see DOXGRP_TYPES, SPIF_CAST_C()
+ */
#define SPIF_NULL_CTYPE(type) (SPIF_CAST_C(type) (NULL))
-/* Converts a type (such as "obj") to a string denoting a NULL object of that type. */
+/**
+ * Returns a string representing a NULL value of the specified base
+ * type.
+ *
+ * This macro returns a string which shows the NULL value typecast to
+ * the specified type. This is a convenience macro used primarily by
+ * the "show" method of various objects.
+ *
+ * @param type The type basename.
+ * @return A string representation of a NULL object of the
+ * specified type.
+ *
+ * @see DOXGRP_TYPES
+ */
#define SPIF_NULLSTR_TYPE(type) "{ ((spif_" #type "_t) NULL) }"
-#define SPIF_NULLSTR_CTYPE(type) "{ ((" #type ") NULL) }"
-/* Our own version of the sizeof() operator since objects are actually pointers. */
-#define SPIF_SIZEOF_TYPE(type) (sizeof(SPIF_CONST_TYPE(type)))
-
-/* Make typedef's easier. */
-#define SPIF_DEFINE_TYPE(t, u) \
-typedef u SPIF_CONST_TYPE(t); \
-typedef SPIF_CONST_TYPE(t) * SPIF_TYPE(t)
+/**
+ * Returns a string representing a NULL value of the specified native
+ * C type.
+ *
+ * This macro returns a string which shows the NULL value typecast to
+ * the specified type. This is a convenience macro used primarily by
+ * the "show" method of various objects.
+ *
+ * @param type The type basename.
+ * @return A string representation of a NULL value of the
+ * specified C type.
+ *
+ * @see DOXGRP_TYPES
+ */
+#define SPIF_NULLSTR_CTYPE(type) "{ ((" #type ") NULL) }"
+/[EMAIL PROTECTED]/
-/* Integer types that are guaranteed to be there and to work...more or less. :) */
+/[EMAIL PROTECTED]/
+/**
+ * @name Sized Integer Data Types
+ * ---
+ *
+ * These type definitions provide integer types which are guaranteed
+ * portable, guaranteed to be of a specific size, and guaranteed to be
+ * signed or unsigned, according to the name of each type.
+ *
+ * @note Platforms not supporting an integer type of a given size
+ * default to @c long
+ *
+ * @note The definitions shown here in the documentation correspond to
+ * the platform on which the docs were generated and do not
+ * necessarily reflect the actual mappings on your platform.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * An 8-bit signed integer.
+ *
+ * An 8-bit signed integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed @INT_8_TYPE@ spif_int8_t;
+
+/**
+ * An 8-bit unsigned integer.
+ *
+ * An 8-bit unsigned integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned @INT_8_TYPE@ spif_uint8_t;
+
+/**
+ * A 16-bit signed integer.
+ *
+ * A 16-bit signed integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed @INT_16_TYPE@ spif_int16_t;
+
+/**
+ * A 16-bit unsigned integer.
+ *
+ * A 16-bit unsigned integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned @INT_16_TYPE@ spif_uint16_t;
+
+/**
+ * A 32-bit signed integer.
+ *
+ * A 32-bit signed integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed @INT_32_TYPE@ spif_int32_t;
+
+/**
+ * A 32-bit unsigned integer.
+ *
+ * A 32-bit unsigned integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned @INT_32_TYPE@ spif_uint32_t;
+
+/**
+ * A 64-bit signed integer.
+ *
+ * A 64-bit signed integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed @INT_64_TYPE@ spif_int64_t;
+
+/**
+ * A 64-bit unsigned integer.
+ *
+ * A 64-bit unsigned integer.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned @INT_64_TYPE@ spif_uint64_t;
+/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
+/**
+ * @name Portable C-Mapped Data Types
+ * ---
+ *
+ * These type definitions provide versions of the native C types which
+ * are specifically signed or unsigned. Also included are an
+ * explicitly-signed char pointer type, a generic pointer type, and a
+ * generic function pointer type.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * A signed char.
+ *
+ * A signed char.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed char spif_char_t;
+
+/**
+ * A signed short.
+ *
+ * A signed short.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed short spif_short_t;
+
+/**
+ * A signed int.
+ *
+ * A signed int.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed int spif_int_t;
+
+/**
+ * A signed long.
+ *
+ * A signed long.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef signed long spif_long_t;
+
+/**
+ * An unsigned char.
+ *
+ * An unsigned char.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned char spif_uchar_t;
+
+/**
+ * An unsigned short.
+ *
+ * An unsigned short.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned short spif_ushort_t;
+
+/**
+ * An unsigned int.
+ *
+ * An unsigned int.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned int spif_uint_t;
+
+/**
+ * An unsigned long.
+ *
+ * An unsigned long.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef unsigned long spif_ulong_t;
-/* Char pointer that enforces signedness of char type */
+/**
+ * A pointer to a signed char.
+ *
+ * A pointer to a signed char.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef spif_char_t *spif_charptr_t;
-/* Socket types */
+/**
+ * A generic, untyped pointer.
+ *
+ * A generic, untyped pointer.
+ *
+ * @see DOXGRP_TYPES
+ */
+typedef void *spif_ptr_t;
+
+/**
+ * A generic function pointer.
+ *
+ * A generic function pointer.
+ *
+ * @see DOXGRP_TYPES
+ */
+typedef spif_ptr_t (*spif_fptr_t)(spif_ptr_t, ...);
+/[EMAIL PROTECTED]/
+
+/[EMAIL PROTECTED]/
+/**
+ * @name Portable Socket Types
+ * ---
+ *
+ * These types provide portability and name-mapping for the values
+ * and types used in socket code. These are used by the LibAST socket
+ * object and should not need to be used in end-user code.
+ *
+ * @bug FIXME: These mappings are currently hard-coded.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * A generic socket address.
+ *
+ * @internal
+ * This type references a generic socket address structure. It is
+ * used for typecasting the protocol-based pointers (see below) to a
+ * generic type suitable for use as a parameter to socket functions.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(sockaddr, struct sockaddr);
+
+/**
+ * A socket address for the IPv4 protocol family.
+ *
+ * @internal
+ * This type references an IPv4 socket address structure. It is used
+ * to store IP addressing information for a given socket.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(ipsockaddr, struct sockaddr_in);
+
+/**
+ * A socket address for the UNIX protocol family.
+ *
+ * @internal
+ * This type references a UNIX socket address structure. It is used
+ * to store addressing information for a given UNIX socket.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(unixsockaddr, struct sockaddr_un);
+
+/**
+ * An IPv4 address.
+ *
+ * @internal
+ * This type references an IPv4 address in native host format.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(ipaddr, struct in_addr);
+
+/**
+ * Host information.
+ *
+ * @internal
+ * This type references host information in native host format.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(hostinfo, struct hostent);
+
+/**
+ * Protocol information.
+ *
+ * @internal
+ * This type references protocol information in native host format.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(protoinfo, struct protoent);
+
+/**
+ * Service information.
+ *
+ * @internal
+ * This type references service information in native host format.
+ *
+ * @see DOXGRP_TYPES
+ */
SPIF_DEFINE_TYPE(servinfo, struct servent);
+
+/**
+ * The file descriptor for a socket.
+ *
+ * This type encapsulates the actual type of the socket file
+ * descriptor.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef int spif_sockfd_t;
+
+/**
+ * The protocol family for a socket.
+ *
+ * This type encapsulates the actual representation of the protocol
+ * family.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef int spif_sockfamily_t;
+
+/**
+ * The type of a socket.
+ *
+ * This type encapsulates the actual representation of the socket
+ * type.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef int spif_socktype_t;
+
+/**
+ * A socket protocol.
+ *
+ * This type encapsulates the actual representation of a socket
+ * protocol.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef int spif_sockproto_t;
+
+/**
+ * A socket port.
+ *
+ * This type encapsulates the actual representation of a socket's
+ * port.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef spif_uint16_t spif_sockport_t;
+
+/**
+ * The length of a socket address structure.
+ *
+ * This type encapsulates the actual representation of the size of a
+ * socket address structure.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef socklen_t spif_sockaddr_len_t;
+/[EMAIL PROTECTED]/
-/* Type for object comparisons */
+/[EMAIL PROTECTED]/
+/**
+ * @name Portable Enumerated Data Types
+ * ---
+ *
+ * These typedefs and macros provide portable, consistent
+ * implementations of arbitrary comparison functionality and boolean
+ * variables.
+ *
+ * @ingroup DOXGRP_TYPES
+ */
+
+/**
+ * An enumerated type for comparisons.
+ *
+ * The defacto standard for the return value of a function or
+ * operation which compares two things comes from the return value of
+ * the @c strcmp() family of functions: An integer less than, equal
+ * to, or greater than zero representing that the first value is less
+ * than, equal to, or greater than (respectively) the second value.
+ * This type makes such comparisons more readable and provides
+ * specific, defined values for each case. Macros are provided to
+ * improve readability and simplify conversion from other comparison
+ * functions.
+ *
+ * @see DOXGRP_TYPES, SPIF_CMP_FROM_INT(), SPIF_CMP_IS_LESS(),
+ * SPIF_CMP_IS_EQUAL(), SPIF_CMP_IS_GREATER()
+ */
typedef enum {
SPIF_CMP_LESS = -1,
SPIF_CMP_EQUAL = 0,
SPIF_CMP_GREATER = 1
} spif_cmp_t;
+
+/**
+ * Convert a traditional integer comparison result to a spif_cmp_t
+ * value.
+ *
+ * This convenience macro accepts an integer value less than, equal
+ * to, or greater than zero (as traditionally supplied by comparison
+ * functions) and converts that value to SPIF_CMP_LESS,
+ * SPIF_CMP_EQUAL, or SPIF_CMP_GREATER, respectively.
+ *
+ * @note This macro evaluates its parameter twice, so beware of side
+ * effects.
+ *
+ * @param i A traditional integer comparison value.
+ * @return The corresponding spif_cmp_t value.
+ *
+ * @see DOXGRP_TYPES, spif_cmp_t
+ */
#define SPIF_CMP_FROM_INT(i) (((i) < 0) ? (SPIF_CMP_LESS) : (((i) > 0) ?
(SPIF_CMP_GREATER) : (SPIF_CMP_EQUAL)))
+
+/**
+ * Check if a comparison value is SPIF_CMP_LESS.
+ *
+ * This convenience macro determines if a given comparison expression
+ * or value evaluates to SPIF_CMP_LESS. The @a cmp expression is only
+ * evaluated once, so this macro can safely be used on comparison
+ * expressions like SPIF_CMP_FROM_INT().
+ *
+ * @param cmp Comparison expression or value of type spif_cmp_t.
+ * @return True if the result is SPIF_CMP_LESS, false otherwise.
+ *
+ * @see DOXGRP_TYPES, spif_cmp_t, SPIF_CMP_FROM_INT()
+ */
#define SPIF_CMP_IS_LESS(cmp) ((cmp) == SPIF_CMP_LESS)
+
+/**
+ * Check if a comparison value is SPIF_CMP_EQUAL.
+ *
+ * This convenience macro determines if a given comparison expression
+ * or value evaluates to SPIF_CMP_EQUAL. The @a cmp expression is
+ * only evaluated once, so this macro can safely be used on comparison
+ * expressions like SPIF_CMP_FROM_INT().
+ *
+ * @param cmp Comparison expression or value of type spif_cmp_t.
+ * @return True if the result is SPIF_CMP_EQUAL, false otherwise.
+ *
+ * @see DOXGRP_TYPES, spif_cmp_t, SPIF_CMP_FROM_INT()
+ */
#define SPIF_CMP_IS_EQUAL(cmp) ((cmp) == SPIF_CMP_EQUAL)
+
+/**
+ * Check if a comparison value is SPIF_CMP_GREATER.
+ *
+ * This convenience macro determines if a given comparison expression
+ * or value evaluates to SPIF_CMP_GREATER. The @a cmp expression is
+ * only evaluated once, so this macro can safely be used on comparison
+ * expressions like SPIF_CMP_FROM_INT().
+ *
+ * @param cmp Comparison expression or value of type spif_cmp_t.
+ * @return True if the result is SPIF_CMP_GREATER, false otherwise.
+ *
+ * @see DOXGRP_TYPES, spif_cmp_t, SPIF_CMP_FROM_INT()
+ */
#define SPIF_CMP_IS_GREATER(cmp) ((cmp) == SPIF_CMP_GREATER)
#undef false
@@ -116,6 +809,22 @@
#undef True
#undef TRUE
+/**
+ * An enumerated type for boolean values.
+ *
+ * Unlike C++, C does not have a native boolean type. Having one,
+ * while strictly not necessary, tends to make for more readable
+ * code. So LibAST defines a boolean type and maps the most common
+ * values into it (i.e., TRUE, True, and true along with FALSE, False,
+ * and false).
+ *
+ * @note Because "false" and "true" are C++ reserved words, compiling
+ * LibAST with a C++ compiler will disable these values as members of
+ * the spif_bool_t data type. For this and other reasons (namely
+ * readability), use of "TRUE" and "FALSE" is preferred.
+ *
+ * @see DOXGRP_TYPES
+ */
typedef enum {
#ifndef __cplusplus
false = 0,
@@ -128,9 +837,6 @@
True = 1,
TRUE = 1
} spif_bool_t;
+/[EMAIL PROTECTED]/
-/* Generic pointer */
-typedef void *spif_ptr_t;
-/* Generic function pointer */
-typedef spif_ptr_t (*spif_fptr_t)(spif_ptr_t, ...);
#endif /* _LIBAST_TYPES_H_ */
-------------------------------------------------------
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/psa00100006ave/direct;at.asp_061203_01/01
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
