Main Page | Modules | Data Structures | File List | Data Fields

Peers (New OR System)
[State Utility Library]


Data Structures

struct  sul_dataobj_header_t
struct  sul_objfield_t
struct  sul_objpeer_t
struct  sul_peer_query_t
struct  sul_peer_record_t

Defines

#define SUL_PEER_NAME(table)   peer_##table##_peer
#define SUL_PEER_PTR(table)   &(SUL_PEER_NAME(table))
#define SUL_PEER_DECLARE(table)   extern sul_objpeer_t SUL_PEER_NAME(table)
#define SUL_PEER_IMPLEMENT(type, table)
#define SUL_PEER_IMPLEMENT_SEQ(type, table, seq)
#define SUL_PEER_FIELDS_BEGIN(table)   sul_objfield_t peer_##table##_fields[] = {
#define SUL_PEER_FIELDS_FIELD(name, type)   { name, type, 0, SUL_FIELD_FLAG_NONE, SUL_FIELD_KT_NONE }
#define SUL_PEER_FIELDS_FIELD_KEY(name, type, id)   { name, type, 0, SUL_FIELD_FLAG_NONE, id }
#define SUL_PEER_FIELDS_PKFLD(name, type)   { name, type, 0, SUL_FIELD_FLAG_PK, SUL_FIELD_KT_ID }
#define SUL_PEER_FIELDS_FKFLD(name, type)   { name, type, 0, SUL_FIELD_FLAG_FK, SUL_FIELD_KT_NONE }
#define SUL_PEER_FIELDS_END()   { NULL, SUL_FIELD_TYPE_NULL, 0, 0, 0 } }

Typedefs

typedef void * sul_objectptr_t
typedef enum sul_field_key_type_e sul_field_key_type_e
typedef enum sul_field_flags_e sul_field_flags_e
typedef enum sul_field_type_e sul_field_type_e
typedef sul_objfield_t sul_objfield_t
typedef sul_objpeer_t sul_objpeer_t
typedef sul_peer_query_t sul_peer_query_t
typedef sul_dataobj_header_t sul_dataobj_header_t
typedef sul_peer_record_t sul_peer_record_t

Enumerations

enum  sul_field_key_type_e {
  SUL_FIELD_KT_NONE = -1, SUL_FIELD_KT_ID = 0, SUL_FIELD_KT_NAME, SUL_FIELD_KT_IP,
  SUL_FIELD_KT_LAST
}
enum  sul_field_flags_e { SUL_FIELD_FLAG_NONE = 0, SUL_FIELD_FLAG_PK, SUL_FIELD_FLAG_FK }
enum  sul_field_type_e {
  SUL_FIELD_TYPE_NULL = 0, SUL_FIELD_TYPE_STRING, SUL_FIELD_TYPE_INTEGER, SUL_FIELD_TYPE_BOOLEAN,
  SUL_FIELD_TYPE_FK, SUL_FIELD_TYPE_REAL, SUL_FIELD_TYPE_TIMESTAMP, SUL_FIELD_TYPE_TIME,
  SUL_FIELD_TYPE_DATE
}

Functions

 sul_peer_initialize (sul_objpeer_t *peer)
 sul_peer_query_execute (sul_peer_query_t **query, sul_objpeer_t *peer, sul_dbc_t *dbc, apr_pool_t *pool, const char *sql,...)
 sul_peer_query_size (sul_peer_query_t *query)
 sul_peer_generate_array (apr_array_header_t **arrayp, sul_peer_query_t *query, apr_pool_t *pool)
 sul_peer_generate_single (sul_objectptr_t *ptr, sul_peer_query_t *query, apr_pool_t *pool)
 sul_peer_type_size (sul_field_type_e type)
 sul_peer_field_to_sql (sul_stringbuf_t *sql, sul_objpeer_t *peer, sul_objectptr_t ptr, apr_size_t fldi, apr_pool_t *pool)
 sul_peer_sql_query (sul_objpeer_t *peer, apr_pool_t *pool)
 sul_peer_sql_add (sul_objpeer_t *peer, sul_objectptr_t ptr, apr_pool_t *pool)
 sul_peer_sql_update (sul_objpeer_t *peer, sul_objectptr_t ptr, apr_pool_t *pool)
 sul_peer_sql_delete (sul_objpeer_t *peer, sul_objectptr_t ptr, apr_pool_t *pool)
 sul_peer_object_key_get (sul_objpeer_t *peer, sul_objectptr_t ptr)
 sul_peer_object_key_set (sul_objpeer_t *peer, sul_objectptr_t ptr, sul_key_t key)
 sul_peer_populate (sul_objectptr_t ptr, sul_peer_query_t *query, apr_size_t row, apr_pool_t *pool)
 sul_peer_save (sul_objpeer_t *peer, sul_objectptr_t ptr, sul_dbc_t *dbc, apr_pool_t *pool)
 sul_peer_add (sul_objpeer_t *peer, sul_objectptr_t ptr, sul_dbc_t *dbc, apr_pool_t *pool)
 sul_peer_delete (sul_objpeer_t *peer, sul_objectptr_t ptr, sul_dbc_t *dbc, apr_pool_t *pool)
 sul_parse_time (apr_time_exp_t *tm, const char *str)

Define Documentation

#define SUL_PEER_DECLARE (  table   )     extern sul_objpeer_t SUL_PEER_NAME(table)
 

Expands to a declaration of a peer for a database table. This macro is intended to be used in header files.

#define SUL_PEER_FIELDS_BEGIN (  table   )     sul_objfield_t peer_##table##_fields[] = {
 

Begins field declarations for a specific object Peer.

Parameters:
table Name of the Table to define the Fields for.

 
SUL_PEER_FIELDS_END (   )     { NULL, SUL_FIELD_TYPE_NULL, 0, 0, 0 } }
 

Ends field declarations for a specific object Peer.

#define SUL_PEER_FIELDS_FIELD (  name,
type   )     { name, type, 0, SUL_FIELD_FLAG_NONE, SUL_FIELD_KT_NONE }
 

Declares a field of the given type.

Parameters:
name Name of the field in the database.
type Type of the field.

#define SUL_PEER_FIELDS_FIELD_KEY (  name,
type,
id   )     { name, type, 0, SUL_FIELD_FLAG_NONE, id }
 

Declares a field of the given type.

Parameters:
name Name of the field in the database.
type Type of the field.
id Name of the key type to encode this field as when generating hash tables of table data and objects.

#define SUL_PEER_FIELDS_FKFLD (  name,
type   )     { name, type, 0, SUL_FIELD_FLAG_FK, SUL_FIELD_KT_NONE }
 

Declares a primary key field.

Parameters:
name Name of the field in the database.
type Type of the field.

#define SUL_PEER_FIELDS_PKFLD (  name,
type   )     { name, type, 0, SUL_FIELD_FLAG_PK, SUL_FIELD_KT_ID }
 

Declares a primary key field.

Parameters:
name Name of the field in the database.
type Type of the field.

#define SUL_PEER_IMPLEMENT (  type,
table   ) 
 

Value:

sul_objpeer_t SUL_PEER_NAME(table) = { \
    #type, \
    #table, \
    #table "_id", \
    sizeof(type), \
    peer_##table##_fields, \
    FALSE \
  }
Implements a peer for the given type and does all the work that SUL_PEER_DECLARE sets us up to do and so this macro goes hand in hand with that one.

Parameters:
type Name of the type which will hold live objects for this Peer.
table Name of the table in the database that contains the data.

#define SUL_PEER_IMPLEMENT_SEQ (  type,
table,
seq   ) 
 

Value:

sul_objpeer_t SUL_PEER_NAME(table) = { \
    #type, \
    #table, \
    #seq, \
    sizeof(type), \
    peer_##table##_fields, \
    FALSE \
  }

#define SUL_PEER_NAME (  table   )     peer_##table##_peer
 

Expands the name of the peer for a database table.

Parameters:
table A table's name.

#define SUL_PEER_PTR (  table   )     &(SUL_PEER_NAME(table))
 

Expands to a pointer to the peer for a database table.

Parameters:
table A table's name.

Typedef Documentation

typedef struct sul_dataobj_header_t sul_dataobj_header_t
 

Object header attached to any "Peer" managed object.

typedef enum sul_field_type_e sul_field_type_e
 

All of the possible field types that mapping is supported for by the Peer system. Any field of this type will be properly converted to and from SQL queries.

typedef void* sul_objectptr_t
 

Type for pointers to an object created and manipulate by the object or functions.

typedef struct sul_objfield_t sul_objfield_t
 

A field in a table with its Name, Type, and other details such as whether or not the field is the primary key of its table.

typedef struct sul_objpeer_t sul_objpeer_t
 

Peer that contains information for mapping rows in a database to and from live objects in the software. Information on each fo the field is also maintained.

typedef struct sul_peer_query_t sul_peer_query_t
 

Query data stored when querying any Peer. Stores the Peer being queried, the database connection and any rows that came back.

Enumeration Type Documentation

enum sul_field_type_e
 

All of the possible field types that mapping is supported for by the Peer system. Any field of this type will be properly converted to and from SQL queries.

Enumeration values:
SUL_FIELD_TYPE_NULL  Invalid field type, used for error situations.
SUL_FIELD_TYPE_STRING  String type that maps directly to a character pointer.
SUL_FIELD_TYPE_INTEGER  Integer type that maps directly to a long integer.
SUL_FIELD_TYPE_BOOLEAN  Boolean type that maps directly to an integer.
SUL_FIELD_TYPE_FK  Foreign key type, these are handled differently than integers when their values are zero.
SUL_FIELD_TYPE_REAL  Floating point type that maps directly to a float.

Function Documentation

sul_peer_add (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
sul_dbc_t *  dbc,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer to translate the object being saved.
ptr The object that needs to be saved.
dbc A database connection to save the object over.
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_delete (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
sul_dbc_t *  dbc,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer to translate the object being saved.
ptr The object that needs to be saved.
dbc A database connection to save the object over.
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_field_to_sql (  sul_stringbuf_t *  sql,
sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
apr_size_t  fldi,
apr_pool_t *  pool
) 
 

Parameters:
sql 
peer 
ptr 
fldi 
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_generate_array (  apr_array_header_t **  arrayp,
sul_peer_query_t *  query,
apr_pool_t *  pool
) 
 

Generates an array containing all of the data objects returned by a Peer query. This call works if the number of rows returned is a positive integer or zero.

Parameters:
arrayp Pointer to receive the array.
query Query that was executed and has the data to return.
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_generate_single (  sul_objectptr_t *  ptr,
sul_peer_query_t *  query,
apr_pool_t *  pool
) 
 

Parameters:
ptr 
query 
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_initialize (  sul_objpeer_t *  peer  ) 
 

Peers MUST be initialized before they can be used. Initializing a peer calculates the offsets of the fields in the data objects and locates the primary key field of the peer, making it easily accessible in future calls. By having the offsets, random access to the peer fields are possible (rather than calculating offsets each time)

Parameters:
peer A peer.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_object_key_get (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr
) 
 

Parameters:
peer A peer that describes the object's fields.
ptr An object.
Returns:
The primary key of the object.

sul_peer_object_key_set (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
sul_key_t  key
) 
 

Parameters:
peer A peer that describes the object's fields.
ptr An object.
key New primary key of the object (see sul_peer_save)
Returns:
The primary key of the object.

sul_peer_populate (  sul_objectptr_t  ptr,
sul_peer_query_t *  query,
apr_size_t  row,
apr_pool_t *  pool
) 
 

Parameters:
ptr The new object to receive the information.
query Query containing the necessary information to build the object.
row Row number in the database rs that should be populated from.
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_query_execute (  sul_peer_query_t **  query,
sul_objpeer_t *  peer,
sul_dbc_t *  dbc,
apr_pool_t *  pool,
const char *  sql,
... 
) 
 

Executes an SQL query for grabbing objects from the specified peer.

Parameters:
query A query object to receive the information.
peer A peer to transform the returned data into objects.
dbc Database connection to execute the query over.
pool A memory pool for overhead.
sql SQL SELECT query that will grab the necessary data.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_query_size (  sul_peer_query_t *  query  ) 
 

Gets the number of rows returned by the peer query. Often used to make sure that a row was returned and if none were, then create a new row.

Parameters:
query A peer query.
Returns:
Number of rows returned by the query.

sul_peer_save (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
sul_dbc_t *  dbc,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer to translate the object being saved.
ptr The object that needs to be saved.
dbc A database connection to save the object over.
pool A memory pool for overhead.
Returns:
An sul_error_t instance if an error occured and NULL otherwise.

sul_peer_sql_add (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer that describes the object's fields.
ptr The object to generate the INSERT SQL for.
pool A memory pool for overhead.
Returns:
An SQL query that will add a new row for the object to the database.

sul_peer_sql_delete (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer that describes the object's fields.
ptr The object to generate the DELETE SQL for.
pool A memory pool for overhead.
Returns:
An SQL query that will delete the given object from the database.

sul_peer_sql_query (  sul_objpeer_t *  peer,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer that describes the object's fields.
pool A memory pool for overhead.
Returns:
An SQL query that will SELECT objects of the given peer from the database.

sul_peer_sql_update (  sul_objpeer_t *  peer,
sul_objectptr_t  ptr,
apr_pool_t *  pool
) 
 

Parameters:
peer A peer that describes the object's fields.
ptr The object to generate the UPDATE SQL for.
pool A memory pool for overhead.
Returns:
An SQL query that will update the object's row in the database.

sul_peer_type_size (  sul_field_type_e  type  ) 
 

Gets the size of the field type in bytes so that the offset into an object can be computed and updated properly. Each SQL type maps directly to a specific C type, so it is very important that the relationship between on this mapping read the introduction to the Peers.

Parameters:
type 
Returns:

Generated on Wed Apr 28 09:38:38 2004 for State by doxygen 1.3.5