Home page | Mailing list | Docs

Last updated: Sat Feb 3 05:01:56 2007

Asterisk developer's documentation :: Codename Pineapple

---

stringfields.h File Reference

---

Detailed Description

String fields in structures.

This file contains objects and macros used to manage string fields in structures without requiring them to be allocated as fixed-size buffers or requiring individual allocations for for each field.

Using this functionality is quite simple... an example structure with three fields is defined like this:

  struct sample_fields {
     int x1;
     AST_DECLARE_STRING_FIELDS(
        AST_STRING_FIELD(name);
        AST_STRING_FIELD(address);
        AST_STRING_FIELD(password);
     );
     long x2;
  };

When an instance of this structure is allocated, the fields (and the pool of storage for them) must be initialized:

  struct sample_fields *sample;
  
  sample = calloc(1, sizeof(*sample));
  if (sample) {
     if (ast_string_field_init(sample, 256)) {
        free(sample);
        sample = NULL;
     }
  }
  
  if (!sample) {
  ...
  }

Fields will default to pointing to an empty string, and will revert to that when ast_string_field_free() is called. This means that a string field will never contain NULL.

Using the fields is much like using regular 'char *' fields in the structure, except that writing into them must be done using wrapper macros defined in this file.

Storing simple values into fields can be done using ast_string_field_set(); more complex values (using printf-style format strings) can be stored using ast_string_field_build().

When the structure instance is no longer needed, the fields and their storage pool must be freed:

  ast_string_field_free_all(sample);
  free(sample);

Definition in file stringfields.h.

#include <string.h>
#include <stdarg.h>
#include <stddef.h>
#include "asterisk/inline_api.h"
#include "asterisk/compiler.h"
#include "asterisk/compat.h"

Include dependency graph for stringfields.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_string_field_mgr
struct	ast_string_field_pool
Defines
#define	AST_DECLARE_STRING_FIELDS(field_list)
	Declare the fields needed in a structure.
#define	AST_STRING_FIELD(name)   const ast_string_field name
	Declare a string field.
#define	ast_string_field_build(x, field, fmt, args...)   ast_string_field_index_build(x, ast_string_field_index(x, field), fmt, args)
	Set a field to a complex (built) value.
#define	ast_string_field_build_va(x, field, fmt, args1, args2)   ast_string_field_index_build_va(x, ast_string_field_index(x, field), fmt, args1, args2)
	Set a field to a complex (built) value.
#define	ast_string_field_count(x)   (offsetof(typeof(*(x)), __end_field) - offsetof(typeof(*(x)), __begin_field)) / sizeof(ast_string_field)
	Get the number of string fields in a structure.
#define	ast_string_field_free(x, field)   ast_string_field_index_free(x, ast_string_field_index(x, field))
	Free a field's value.
#define	ast_string_field_free_all(x)
	Free the stringfields in a structure.
#define	ast_string_field_free_pools(x)
	Free the stringfield storage pools attached to a structure.
#define	ast_string_field_index(x, field)   (offsetof(typeof(*x), field) - offsetof(typeof(*x), __begin_field)) / sizeof(ast_string_field)
	Get the index of a field in a structure.
#define	ast_string_field_index_build(x, index, fmt, args...)   __ast_string_field_index_build(&(x)->__field_mgr, &(x)->__begin_field[0], ast_string_field_count(x), index, fmt, args)
	Set a field to a complex (built) value.
#define	ast_string_field_index_build_va(x, index, fmt, args1, args2)   __ast_string_field_index_build_va(&(x)->__field_mgr, &(x)->__begin_field[0], ast_string_field_count(x), index, fmt, args1, args2)
	Set a field to a complex (built) value with prebuilt va_lists.
#define	ast_string_field_index_free(x, index)
	Free a field's value.
#define	ast_string_field_index_set(x, index, data)
	Set a field to a simple string value.
#define	ast_string_field_init(x, size)   __ast_string_field_init(&(x)->__field_mgr, size, &(x)->__begin_field[0], ast_string_field_count(x))
	Initialize a field pool and fields.
#define	ast_string_field_set(x, field, data)   ast_string_field_index_set(x, ast_string_field_index(x, field), data)
	Set a field to a simple string value.
Typedefs
typedef const char *	ast_string_field
Functions
ast_string_field	__ast_string_field_alloc_space (struct ast_string_field_mgr *mgr, size_t needed, ast_string_field *fields, int num_fields)
void	__ast_string_field_index_build (struct ast_string_field_mgr *mgr, ast_string_field *fields, int num_fields, int index, const char *format,...)
void	__ast_string_field_index_build_va (struct ast_string_field_mgr *mgr, ast_string_field *fields, int num_fields, int index, const char *format, va_list a1, va_list a2)
int	__ast_string_field_init (struct ast_string_field_mgr *mgr, size_t size, ast_string_field *fields, int num_fields)
Variables
const char	__ast_string_field_empty []

---

Define Documentation

#define AST_DECLARE_STRING_FIELDS (  field_list   )

Value: ast_string_field __begin_field[0]; \ field_list \ ast_string_field __end_field[0]; \ struct ast_string_field_mgr __field_mgr Declare the fields needed in a structure. Parameters: field_list  The list of fields to declare, using AST_STRING_FIELD() for each one Definition at line 196 of file stringfields.h.

#define AST_STRING_FIELD (  name   )     const ast_string_field name

Declare a string field. Parameters: name  The field name Definition at line 190 of file stringfields.h.

#define ast_string_field_build (  x, field, fmt, args...   )     ast_string_field_index_build(x, ast_string_field_index(x, field), fmt, args)

Set a field to a complex (built) value. Parameters: x  Pointer to a structure containing fields field  Name of the field to set fmt  printf-style format string args  Arguments for format string Returns: nothing Definition at line 314 of file stringfields.h. Referenced by build_callid_pvt(), build_callid_registry(), build_contact(), build_rpid(), build_user(), build_via(), check_auth(), create_addr_from_peer(), handle_request_subscribe(), handle_response(), handle_response_invite(), mgcp_new(), parse_moved_contact(), parse_register_contact(), sip_register(), sip_sipredirect(), and transmit_fake_auth_response().

#define ast_string_field_build_va (  x, field, fmt, args1, args2   )     ast_string_field_index_build_va(x, ast_string_field_index(x, field), fmt, args1, args2)

Set a field to a complex (built) value. Parameters: x  Pointer to a structure containing fields field  Name of the field to set fmt  printf-style format string argslist  a va_list of the args Returns: nothing Definition at line 325 of file stringfields.h.

#define ast_string_field_count (  x   )     (offsetof(typeof(*(x)), __end_field) - offsetof(typeof(*(x)), __begin_field)) / sizeof(ast_string_field)

Get the number of string fields in a structure. Parameters: x  Pointer to a structure containing fields Returns: the number of fields in the structure's definition Definition at line 207 of file stringfields.h.

#define ast_string_field_free (  x, field   )     ast_string_field_index_free(x, ast_string_field_index(x, field))

Free a field's value. Parameters: x  Pointer to a structure containing fields field  Name of the field to free Returns: nothing Note: Because of the storage pool used, the memory occupied by the field's value is not recovered; the field pointer is just changed to point to an empty string. Definition at line 352 of file stringfields.h. Referenced by check_peer_ok(), check_user_full(), handle_request_invite(), handle_response_invite(), parse_register_contact(), sip_request_call(), and transmit_register().

#define ast_string_field_free_all (  x   )

Free the stringfields in a structure. Parameters: x  Pointer to a structure containing fields Returns: nothing After calling this macro, the most recently allocated pool attached to the structure will be available for use by stringfields again. Definition at line 381 of file stringfields.h. Referenced by transmit_response_using_temp().

#define ast_string_field_free_pools (  x   )

Free the stringfield storage pools attached to a structure. Parameters: x  Pointer to a structure containing fields Returns: nothing After calling this macro, fields can no longer be accessed in structure; it should only be called immediately before freeing the structure itself. Definition at line 364 of file stringfields.h. Referenced by ast_channel_free(), build_peer(), build_user(), destroy_peer(), destroy_user(), iax2_destroy(), sip_destroy_device(), sip_registry_destroy(), and temp_pvt_cleanup().

#define ast_string_field_index (  x, field   )     (offsetof(typeof(*x), field) - offsetof(typeof(*x), __begin_field)) / sizeof(ast_string_field)

Get the index of a field in a structure. Parameters: x  Pointer to a structure containing fields field  Name of the field to locate Returns: the position (index) of the field within the structure's array of fields Definition at line 217 of file stringfields.h. Referenced by reply_digest().

#define ast_string_field_index_build (  x, index, fmt, args...   )     __ast_string_field_index_build(&(x)->__field_mgr, &(x)->__begin_field[0], ast_string_field_count(x), index, fmt, args)

Set a field to a complex (built) value. Parameters: x  Pointer to a structure containing fields index  Index position of the field within the structure fmt  printf-style format string args  Arguments for format string Returns: nothing Definition at line 291 of file stringfields.h.

#define ast_string_field_index_build_va (  x, index, fmt, args1, args2   )     __ast_string_field_index_build_va(&(x)->__field_mgr, &(x)->__begin_field[0], ast_string_field_count(x), index, fmt, args1, args2)

Set a field to a complex (built) value with prebuilt va_lists. Parameters: x  Pointer to a structure containing fields index  Index position of the field within the structure fmt  printf-style format string args1  Arguments for format string in va_list format args2  a second copy of the va_list for the sake of bsd, with no va_list copy operation Returns: nothing Definition at line 303 of file stringfields.h.

#define ast_string_field_index_free (  x, index   )

Value: do { \ (x)->__begin_field[index] = __ast_string_field_empty; \ } while(0) Free a field's value. Parameters: x  Pointer to a structure containing fields index  Index position of the field within the structure Returns: nothing Note: Because of the storage pool used, the memory occupied by the field's value is not recovered; the field pointer is just changed to point to an empty string. Definition at line 338 of file stringfields.h.

#define ast_string_field_index_set (  x, index, data   )

Set a field to a simple string value. Parameters: x  Pointer to a structure containing fields index  Index position of the field within the structure data  String value to be copied into the field Returns: nothing Definition at line 236 of file stringfields.h. Referenced by reply_digest().

#define ast_string_field_init (  x, size   )     __ast_string_field_init(&(x)->__field_mgr, size, &(x)->__begin_field[0], ast_string_field_count(x))

Initialize a field pool and fields. Parameters: x  Pointer to a structure containing fields size  Amount of storage to allocate Returns: 0 on success, non-zero on failure Definition at line 226 of file stringfields.h. Referenced by ast_channel_alloc(), build_device(), build_peer(), build_user(), new_iax(), sip_alloc(), sip_register(), temp_pvt_init(), and transmit_response_using_temp().

#define ast_string_field_set (  x, field, data   )     ast_string_field_index_set(x, ast_string_field_index(x, field), data)

Set a field to a simple string value. Parameters: x  Pointer to a structure containing fields field  Name of the field to set data  String value to be copied into the field Returns: nothing Definition at line 275 of file stringfields.h. Referenced by __oh323_new(), agent_new(), alsa_new(), ast_cdr_setaccount(), ast_change_name(), ast_do_masquerade(), ast_iax2_new(), authenticate_reply(), authenticate_request(), begin_dial(), build_device(), build_peer(), build_rpid(), build_user(), check_access(), check_peer_ok(), check_user_full(), check_user_ok(), create_addr(), create_addr_from_peer(), extract_uri(), features_call(), get_also_info(), get_destination(), get_rdnis(), gtalk_new(), handle_request(), handle_request_bye(), handle_request_invite(), handle_request_options(), handle_request_refer(), handle_request_subscribe(), handle_response(), iax2_call(), iax2_request(), jingle_new(), local_call(), mgcp_new(), moh2_exec(), nbs_new(), new_iax(), oss_new(), ourdialogbranch(), parse_moved_contact(), parse_ok_contact(), parse_register_contact(), phone_new(), read_config(), register_verify(), registry_authrequest(), replace_cid(), set_device_defaults(), sip_alloc(), sip_call(), sip_new(), sip_poke_peer(), sip_register(), sip_request_call(), sip_set_redirstr(), skinny_new(), socket_process(), transmit_refer(), transmit_register(), and transmit_response_using_temp().

---

Typedef Documentation

typedef const char* ast_string_field

Definition at line 100 of file stringfields.h.

---

Function Documentation

ast_string_field __ast_string_field_alloc_space (  struct ast_string_field_mgr *  mgr, size_t  needed, ast_string_field *  fields, int  num_fields )

Definition at line 874 of file utils.c. References add_string_pool(), ast_string_field_pool::base, ast_string_field_mgr::pool, ast_string_field_mgr::size, ast_string_field_mgr::space, and ast_string_field_mgr::used. { char *result = NULL; if (__builtin_expect(needed > mgr->space, 0)) { size_t new_size = mgr->size * 2; while (new_size < needed) new_size *= 2; if (add_string_pool(mgr, new_size)) return NULL; } result = mgr->pool->base + mgr->used; mgr->used += needed; mgr->space -= needed; return result; }

void __ast_string_field_index_build (  struct ast_string_field_mgr *  mgr, ast_string_field *  fields, int  num_fields, int  index, const char *  format,   ... )

Definition at line 922 of file utils.c. References __ast_string_field_index_build_va(). { va_list ap1, ap2; va_start(ap1, format); va_start(ap2, format); /* va_copy does not exist on FreeBSD */ __ast_string_field_index_build_va(mgr, fields, num_fields, index, format, ap1, ap2); va_end(ap1); va_end(ap2); }

void __ast_string_field_index_build_va (  struct ast_string_field_mgr *  mgr, ast_string_field *  fields, int  num_fields, int  index, const char *  format, va_list  a1, va_list  a2 )

Definition at line 895 of file utils.c. References add_string_pool(), ast_string_field_pool::base, ast_string_field_mgr::pool, ast_string_field_mgr::size, ast_string_field_mgr::space, and ast_string_field_mgr::used. Referenced by __ast_string_field_index_build(). { size_t needed; needed = vsnprintf(mgr->pool->base + mgr->used, mgr->space, format, ap1) + 1; va_end(ap1); if (needed > mgr->space) { size_t new_size = mgr->size * 2; while (new_size < needed) new_size *= 2; if (add_string_pool(mgr, new_size)) return; vsprintf(mgr->pool->base + mgr->used, format, ap2); } fields[index] = mgr->pool->base + mgr->used; mgr->used += needed; mgr->space -= needed; }

int __ast_string_field_init (  struct ast_string_field_mgr *  mgr, size_t  size, ast_string_field *  fields, int  num_fields )

Definition at line 860 of file utils.c. References add_string_pool(). { int index; if (add_string_pool(mgr, size)) return -1; for (index = 0; index < num_fields; index++) fields[index] = __ast_string_field_empty; return 0; }

---

Variable Documentation

const char __ast_string_field_empty[]

Definition at line 842 of file utils.c.

---

Asterisk is a trademark for Digium, inc.. | Edvina.net | Asterisk.org | This documentation was generated with Doxygen