Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
stringfields.h File Reference
#include "asterisk/inline_api.h"
#include "asterisk/vector.h"

Go to the source code of this file.

Data Structures

struct  ast_string_field_mgr
 
struct  ast_string_field_pool
 
struct  ast_string_field_vector
 

Macros

#define __ast_string_field_ptr_set_by_fields(field_mgr_pool, field_mgr, ptr, data, file, lineno, func)
 
#define ast_calloc_with_stringfields(n, type, size)
 Allocate a structure with embedded stringfields in a single allocation. More...
 
#define AST_DECLARE_STRING_FIELDS(field_list)
 Declare the fields needed in a structure. More...
 
#define AST_STRING_FIELD(name)   const ast_string_field name
 Declare a string field. More...
 
#define AST_STRING_FIELD_ALLOCATION(x)   *((ast_string_field_allocation *) (x - __alignof__(ast_string_field_allocation)))
 Macro to provide access to the allocation field that lives immediately in front of a string field. More...
 
#define ast_string_field_build(x, field, fmt, args...)
 Set a field to a complex (built) value. More...
 
#define ast_string_field_build_va(x, field, fmt, args)
 Set a field to a complex (built) value. More...
 
#define AST_STRING_FIELD_EXTENDED(name)   AST_STRING_FIELD(name)
 Declare an extended string field. More...
 
#define ast_string_field_free_memory(x)
 free all memory - to be called before destroying the object More...
 
#define ast_string_field_init(x, size)
 Initialize a field pool and fields. More...
 
#define ast_string_field_init_extended(x, field)
 Initialize an extended string field. More...
 
#define ast_string_field_ptr_build(x, ptr, fmt, args...)
 Set a field to a complex (built) value. More...
 
#define ast_string_field_ptr_build_va(x, ptr, fmt, args)
 Set a field to a complex (built) value with prebuilt va_lists. More...
 
#define ast_string_field_ptr_set(x, ptr, data)
 Set a field to a simple string value. More...
 
#define ast_string_field_ptr_set_by_fields(field_mgr_pool, field_mgr, ptr, data)   __ast_string_field_ptr_set_by_fields(field_mgr_pool, field_mgr, ptr, data, __FILE__, __LINE__, __PRETTY_FUNCTION__)
 
#define ast_string_field_set(x, field, data)
 Set a field to a simple string value. More...
 
#define ast_string_fields_cmp(instance1, instance2)
 Compare the string fields in two instances of the same structure. More...
 
#define ast_string_fields_copy(copy, orig)
 Copy all string fields from one instance to another of the same structure. More...
 

Typedefs

typedef const char * ast_string_field
 
typedef uint16_t ast_string_field_allocation
 

Enumerations

enum  ast_stringfield_cleanup_type { AST_STRINGFIELD_RESET = 0, AST_STRINGFIELD_DESTROY = -1 }
 

Functions

void * __ast_calloc_with_stringfields (unsigned int num_structs, size_t struct_size, size_t field_mgr_offset, size_t field_mgr_pool_offset, size_t pool_size, const char *file, int lineno, const char *func)
 
ast_string_field __ast_string_field_alloc_space (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, size_t needed, const char *file, int lineno, const char *func)
 
int __ast_string_field_free_memory (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, enum ast_stringfield_cleanup_type cleanup_type, const char *file, int lineno, const char *func)
 Internal cleanup function.
 
int __ast_string_field_init (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, int needed, const char *file, int lineno, const char *func)
 Internal initialization function.
 
void __ast_string_field_ptr_build (const char *file, int lineno, const char *func, struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, ast_string_field *ptr, const char *format,...)
 
void __ast_string_field_ptr_build_va (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, ast_string_field *ptr, const char *format, va_list ap, const char *file, int lineno, const char *func)
 
int __ast_string_field_ptr_grow (struct ast_string_field_mgr *mgr, struct ast_string_field_pool **pool_head, size_t needed, const ast_string_field *ptr)
 
void __ast_string_field_release_active (struct ast_string_field_pool *pool_head, const ast_string_field ptr)
 
int __ast_string_fields_cmp (struct ast_string_field_vector *left, struct ast_string_field_vector *right)
 
int __ast_string_fields_copy (struct ast_string_field_pool *copy_pool, struct ast_string_field_mgr *copy_mgr, struct ast_string_field_mgr *orig_mgr, const char *file, int lineno, const char *func)
 

Variables

const char * __ast_string_field_empty
 

Macro Definition Documentation

#define ast_calloc_with_stringfields (   n,
  type,
  size 
)
Value:
__ast_calloc_with_stringfields(n, sizeof(type), offsetof(type, __field_mgr), \
offsetof(type, __field_mgr_pool), size, __FILE__, __LINE__, __PRETTY_FUNCTION__)
enum ast_media_type type
The type of media the stream is handling.
Definition: stream.c:85

Allocate a structure with embedded stringfields in a single allocation.

Parameters
nCurrent implementation only allows 1 structure to be allocated
typeThe type of structure to allocate
sizeThe number of bytes of space (minimum) to allocate for stringfields to use in each structure

This function will allocate memory for one or more structures that use stringfields, and also allocate space for the stringfields and initialize the stringfield management structure embedded in the outer structure.

Since
1.8

Definition at line 432 of file stringfields.h.

Referenced by build_profile(), and raise_exception().

#define AST_DECLARE_STRING_FIELDS (   field_list)
Value:
struct ast_string_field_pool *__field_mgr_pool; \
field_list \
struct ast_string_field_mgr __field_mgr

Declare the fields needed in a structure.

Parameters
field_listThe list of fields to declare, using AST_STRING_FIELD() for each one. Internally, string fields are stored as a pointer to the head of the pool, followed by individual string fields, and then a struct ast_string_field_mgr which describes the space allocated. We split the two variables so they can be used as markers around the field_list, and this allows us to determine how many entries are in the field, and play with them. In particular, for writing to the fields, we rely on __field_mgr_pool to be a non-const pointer, so we know it has the same size as ast_string_field, and we can use it to locate the fields.
Examples:
app_skel.c.

Definition at line 341 of file stringfields.h.

#define AST_STRING_FIELD (   name)    const ast_string_field name

Declare a string field.

Parameters
nameThe field name
Examples:
app_skel.c.

Definition at line 303 of file stringfields.h.

#define AST_STRING_FIELD_ALLOCATION (   x)    *((ast_string_field_allocation *) (x - __alignof__(ast_string_field_allocation)))

Macro to provide access to the allocation field that lives immediately in front of a string field.

Parameters
xPointer to the string field

Note that x must be a pointer to a byte-sized type – normally (char *) – or this calculation would break horribly

Definition at line 465 of file stringfields.h.

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

Set a field to a complex (built) value.

Parameters
xPointer to a structure containing fields
fieldName of the field to set
fmtprintf-style format string
argsArguments for format string

Definition at line 555 of file stringfields.h.

Referenced by ast_ari_bridges_record(), ast_ari_channels_record(), ast_endpoint_snapshot_create(), build_peer(), build_profile(), build_user(), fax_gateway_framehook(), jingle_alloc(), parking_lot_cfg_create_extensions(), spandsp_fax_gateway_cleanup(), and t30_phase_e_handler().

#define ast_string_field_build_va (   x,
  field,
  fmt,
  args 
)

Set a field to a complex (built) value.

Parameters
xPointer to a structure containing fields
fieldName of the field to set
fmtprintf-style format string
argsArguments for format string in va_list format

Definition at line 591 of file stringfields.h.

Referenced by ast_msg_set_body(), ast_msg_set_context(), ast_msg_set_endpoint(), ast_msg_set_exten(), ast_msg_set_from(), ast_msg_set_tech(), ast_msg_set_to(), ast_refer_set_endpoint(), ast_refer_set_from(), ast_refer_set_refer_to(), ast_refer_set_tech(), and ast_refer_set_to().

#define AST_STRING_FIELD_EXTENDED (   name)    AST_STRING_FIELD(name)

Declare an extended string field.

Since
13.9.0
Parameters
nameThe field name

Definition at line 311 of file stringfields.h.

#define ast_string_field_free_memory (   x)
#define ast_string_field_init (   x,
  size 
)
#define ast_string_field_init_extended (   x,
  field 
)

Initialize an extended string field.

Since
13.9.0
Parameters
xPointer to a structure containing the field
fieldThe extended field to initialize
Return values
zeroon success
non-zeroon error
Note
This macro must be called on ALL fields defined with AST_STRING_FIELD_EXTENDED after ast_string_field_init has been called.

Definition at line 401 of file stringfields.h.

#define ast_string_field_ptr_build (   x,
  ptr,
  fmt,
  args... 
)

Set a field to a complex (built) value.

Parameters
xPointer to a structure containing fields
ptrPointer to a field within the structure
fmtprintf-style format string
argsArguments for format string

Definition at line 537 of file stringfields.h.

#define ast_string_field_ptr_build_va (   x,
  ptr,
  fmt,
  args 
)

Set a field to a complex (built) value with prebuilt va_lists.

Parameters
xPointer to a structure containing fields
ptrPointer to a field within the structure
fmtprintf-style format string
argsArguments for format string in va_list format

Definition at line 573 of file stringfields.h.

Referenced by ast_manager_event_blob_create().

#define ast_string_field_ptr_set (   x,
  ptr,
  data 
)

Set a field to a simple string value.

Parameters
xPointer to a structure containing fields
ptrPointer to a field within the structure
dataString value to be copied into the field
Return values
zeroon success
non-zeroon error

Definition at line 475 of file stringfields.h.

Referenced by ast_parse_digest().

#define ast_string_field_set (   x,
  field,
  data 
)

Set a field to a simple string value.

Parameters
xPointer to a structure containing fields
fieldName of the field to set
dataString value to be copied into the field
Return values
zeroon success
non-zeroon error
Examples:
app_skel.c.

Definition at line 521 of file stringfields.h.

Referenced by __find_callno(), acf_faxopt_write(), ast_bridge_snapshot_create(), ast_bucket_alloc(), ast_bucket_file_alloc(), ast_cdr_fork(), ast_channel_set_bridge_role_option(), ast_endpoint_snapshot_create(), ast_manager_register2(), ast_msg_alloc(), ast_parked_call_payload_create(), ast_parse_digest(), ast_register_application2(), ast_xmpp_client_config_alloc(), attended_transfer_properties_alloc(), authenticate_reply(), authenticate_request(), bridge_base_init(), build_calendar(), build_peer(), build_profile(), build_route(), build_user(), cdr_object_alloc(), cdr_object_create_and_append(), fax_gateway_attach(), fax_gateway_detect_t38(), fax_gateway_framehook(), fax_gateway_start(), feature_attended_transfer(), generic_fax_exec(), handle_bridge_leave_message(), handle_options(), init_queue(), jingle_alloc(), jingle_endpoint_alloc(), jingle_interpret_description(), new_realtime_sqlite3_db(), parking_lot_cfg_alloc(), parking_lot_cfg_remove_extensions(), process_description_file(), queue_set_param(), raise_exception(), receivefax_exec(), register_verify(), sendfax_exec(), set_config(), set_pvt_defaults(), skel_level_alloc(), stasis_app_bridge_playback_channel_add(), stasis_app_control_play_uri(), stasis_app_recording_options_create(), t30_phase_e_handler(), update_realtime_sqlite3_db(), vm_msg_snapshot_create(), and xmpp_client_alloc().

#define ast_string_fields_cmp (   instance1,
  instance2 
)

Compare the string fields in two instances of the same structure.

Since
12
Parameters
instance1The first instance of the structure to be compared
instance2The second instance of the structure to be compared
Return values
zeroif all string fields are equal (does not compare non-string field data)
non-zeroif the values of the string fields differ

Definition at line 610 of file stringfields.h.

#define ast_string_fields_copy (   copy,
  orig 
)

Copy all string fields from one instance to another of the same structure.

Since
12
Parameters
copyThe instance of the structure to be copied into
origThe instance of the structure to be copied from
Return values
zeroon success
non-zeroon error

Definition at line 630 of file stringfields.h.

Enumeration Type Documentation

Enumerator
AST_STRINGFIELD_RESET 

Reset all string fields and free all extra pools that may have been created The allocation or structure can be reused as is.

AST_STRINGFIELD_DESTROY 

Reset all string fields and free all pools. If the pointer was returned by ast_calloc_with_stringfields, it can NOT be reused and should be immediately freed. Otherwise, you must call ast_string_field_init again if you want to reuse it.

Definition at line 313 of file stringfields.h.

313  {
314  /*!
315  * Reset all string fields and free all extra pools that may have been created
316  * The allocation or structure can be reused as is.
317  */
319  /*!
320  * Reset all string fields and free all pools.
321  * If the pointer was returned by ast_calloc_with_stringfields, it can NOT be reused
322  * and should be immediately freed. Otherwise, you must call ast_string_field_init
323  * again if you want to reuse it.
324  */
326 };