stringfields.h File Reference

#include "asterisk/inline_api.h"
#include "asterisk/vector.h"

Include dependency graph for stringfields.h:

Go to the source code of this file.

Data Structures
struct	ast_string_field_mgr
struct	ast_string_field_pool

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. More...
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. More...
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)
	AST_VECTOR (ast_string_field_vector, const char **)

Variables
const char *	__ast_string_field_empty

Macro Definition Documentation

__ast_string_field_ptr_set_by_fields

#define __ast_string_field_ptr_set_by_fields	(		field_mgr_pool,
			field_mgr,
			ptr,
			data,
			file,
			lineno,
			func
	)

Definition at line 479 of file stringfields.h.

Referenced by __ast_string_fields_copy().

ast_calloc_with_stringfields

#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__)

Allocate a structure with embedded stringfields in a single allocation.

Parameters

n	Current imlementation only allows 1 structure to be allocated
type	The type of structure to allocate
size	The 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 426 of file stringfields.h.

Referenced by alloc_header(), append_mailbox_mapping(), AST_TEST_DEFINE(), build_profile(), format_log_message_ap(), jack_data_alloc(), load_config(), load_module(), raise_exception(), and sip_refer_alloc().

AST_DECLARE_STRING_FIELDS

#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_list

The 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.

Definition at line 337 of file stringfields.h.

Referenced by AST_TEST_DEFINE().

AST_STRING_FIELD

#define AST_STRING_FIELD

(

name

)

const ast_string_field name

Declare a string field.

Parameters

name	The field name

Definition at line 299 of file stringfields.h.

Referenced by AST_TEST_DEFINE().

AST_STRING_FIELD_ALLOCATION

#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

x	Pointer 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 460 of file stringfields.h.

Referenced by __ast_string_field_alloc_space(), __ast_string_field_ptr_build_va(), __ast_string_field_ptr_grow(), __ast_string_field_release_active(), and AST_TEST_DEFINE().

ast_string_field_build

#define ast_string_field_build	(		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 550 of file stringfields.h.

Referenced by action_originate(), ast_ari_bridges_record(), ast_ari_channels_record(), ast_endpoint_snapshot_create(), build_callid_pvt(), build_callid_registry(), build_contact(), build_localtag_registry(), build_nonce(), build_peer(), build_profile(), build_user(), caldav_write_event(), endpoint_internal_create(), fax_gateway_framehook(), get_refer_info(), handle_request_subscribe(), init_acf_query(), jingle_alloc(), load_config(), make_our_tag(), mwi_create_state(), parking_lot_cfg_create_extensions(), parse_cdata(), parse_register_contact(), set_target_uri(), sip_sendhtml(), sip_sipredirect(), spandsp_fax_gateway_cleanup(), stasis_app_stored_recording_find_by_name(), and t30_phase_e_handler().

ast_string_field_build_va

#define ast_string_field_build_va	(		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 in va_list format

Returns

nothing

Definition at line 588 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(), and ast_msg_set_to().

AST_STRING_FIELD_EXTENDED

#define AST_STRING_FIELD_EXTENDED

(

name

)

AST_STRING_FIELD(name)

Declare an extended string field.

Since

13.9.0

Parameters

name	The field name

Definition at line 307 of file stringfields.h.

Referenced by AST_TEST_DEFINE().

ast_string_field_free_memory

#define ast_string_field_free_memory

(

x

)

free all memory - to be called before destroying the object

Parameters

x

Definition at line 368 of file stringfields.h.

Referenced by action_destroy(), agent_cfg_destructor(), agent_pvt_destructor(), aor_destroy(), ast_applicationmap_item_destructor(), ast_bridge_features_limits_destroy(), ast_channel_internal_cleanup(), ast_custom_function_unregister(), AST_TEST_DEFINE(), ast_unregister_application(), ast_xml_doc_item_destructor(), ast_xmpp_client_config_destructor(), asterisk_publication_config_destroy(), attended_transfer_properties_destructor(), auth_destroy(), auth_http_callback(), bridge_profile_sounds_destroy_cb(), bridge_role_destroy(), bridge_snapshot_dtor(), bucket_destroy(), build_user(), caldav_destructor(), calendar_destructor(), calendar_event_destructor(), cdr_object_dtor(), cel_general_config_dtor(), channel_snapshot_base_dtor(), channel_snapshot_caller_dtor(), channel_snapshot_dialplan_dtor(), conf_general_dtor(), contact_destroy(), copy_to_voicemail(), db_destructor(), destroy_bridge(), destroy_fast_originate_helper(), destroy_header(), destroy_jack_data(), destroy_mailbox_mapping(), destroy_odbc(), destroy_queue(), destroy_session_details(), device_state_subscription_destroy(), domain_alias_destroy(), endpoint_destructor(), endpoint_dtor(), endpoint_snapshot_dtor(), ewscal_destructor(), exception_store_free(), exchangecal_destructor(), featuregroup_item_destructor(), featuremap_config_destructor(), free_acf_query(), free_config(), free_outgoing(), general_destructor(), global_destructor(), hepv3_config_dtor(), icalendar_destructor(), info_configuration_destroy(), ip_identify_destroy(), jingle_endpoint_destructor(), jingle_session_destructor(), load_module(), logmsg_free(), manager_event_blob_dtor(), mapping_destroy(), media_configuration_destroy(), media_variant_destroy(), mixmonitor_free(), msg_data_destructor(), msg_destructor(), mwi_state_dtor(), parked_call_payload_destructor(), parking_lot_cfg_destructor(), parking_lot_destructor(), peer_destructor(), pickup_destructor(), playback_dtor(), presence_state_dtor(), prometheus_general_config_dtor(), pvt_destructor(), queue_stasis_data_destructor(), realtime_multi_odbc(), realtime_odbc(), recording_options_dtor(), sip_contact_status_dtor(), sip_destroy_peer(), sip_monitor_instance_destructor(), sip_outbound_publish_destroy(), sip_outbound_registration_destroy(), sip_pvt_dtor(), sip_refer_destroy(), sip_registry_destroy(), sip_subscribe_mwi_destroy(), sip_transport_destroy(), skel_global_config_destructor(), skel_level_destructor(), sla_station_destructor(), sla_trunk_destructor(), stasis_app_bridge_channel_wrapper_destructor(), stir_shaken_certificate_destructor(), stir_shaken_general_destructor(), stir_shaken_store_destructor(), store_odbc(), stored_recording_dtor(), subscription_configuration_destroy(), tds_unload_module(), temp_pvt_cleanup(), test_item_destructor(), test_vm_api_destroy_mock_snapshot(), unbound_global_config_destructor(), update_odbc(), user_destructor(), vm_msg_snapshot_destroy(), and xfer_destructor().

ast_string_field_init

#define ast_string_field_init	(		x,
			size
	)

Initialize a field pool and fields.

Parameters

x	Pointer to a structure containing fields
size	Amount of storage to allocate. Use AST_STRINGFIELD_RESET to reset fields to the default value, and release all but the most recent pool. AST_STRINGFIELD_DESTROY (used internally) means free all pools which is equivalent to calling ast_string_field_free_memory.

Returns

0 on success, non-zero on failure

Definition at line 353 of file stringfields.h.

Referenced by __ast_channel_internal_alloc(), __features_config_alloc(), __sip_alloc(), acf_retrieve_docs(), action_originate(), agent_cfg_alloc(), agent_pvt_new(), alloc_new_parking_lot(), alloc_queue(), aor_alloc(), applicationmap_item_alloc(), ast_bridge_features_limits_construct(), ast_bridge_snapshot_create(), ast_calendar_event_alloc(), ast_cel_general_config_alloc(), ast_endpoint_snapshot_create(), ast_manager_event_blob_create(), ast_manager_register2(), ast_msg_alloc(), ast_parked_call_payload_create(), ast_phoneprov_provider_register(), ast_register_application2(), ast_sip_endpoint_alloc(), AST_TEST_DEFINE(), ast_xml_doc_item_alloc(), ast_xmpp_client_config_alloc(), asterisk_publication_config_alloc(), attended_transfer_properties_alloc(), auth_alloc(), auth_http_callback(), bridge_alloc(), bridge_moh_create(), bridge_profile_sounds_alloc(), bucket_alloc(), bucket_file_alloc(), build_calendar(), build_peer(), build_profile(), build_route(), build_user(), caldav_load_calendar(), cdr_object_alloc(), channel_snapshot_base_create(), channel_snapshot_caller_create(), channel_snapshot_dialplan_create(), conf_alloc(), contact_alloc(), copy_to_voicemail(), destroy_odbc(), device_state_subscription_create(), domain_alias_alloc(), endpoint_internal_create(), ewscal_load_calendar(), exchangecal_load_calendar(), featuregroup_handler(), global_alloc(), global_config_alloc(), hepv3_config_alloc(), ical_load_calendar(), init_acf_query(), init_info_configuration(), init_media_configuration(), init_pvt(), init_subscription_configuration(), ip_identify_alloc(), jingle_alloc(), jingle_endpoint_alloc(), launch_monitor_thread(), mapping_alloc(), media_variant_alloc(), msg_data_alloc(), mwi_create_state(), new_iax(), new_outgoing(), new_realtime_sqlite3_db(), parking_lot_cfg_alloc(), playback_create(), presence_state_alloc(), prometheus_general_config_alloc(), queue_stasis_data_alloc(), realtime_multi_odbc(), realtime_odbc(), recording_alloc(), session_details_new(), setup_bridge_role_option(), sip_contact_status_alloc(), sip_monitor_instance_init(), sip_outbound_publish_alloc(), sip_outbound_registration_alloc(), sip_register(), sip_subscribe_mwi(), sip_transport_alloc(), skel_config_alloc(), skel_level_alloc(), sla_build_station(), sla_build_trunk(), stasis_app_bridge_playback_channel_add(), stasis_app_recording_options_create(), stir_shaken_certificate_alloc(), stir_shaken_general_alloc(), stir_shaken_store_alloc(), store_odbc(), tds_load_module(), temp_peer(), temp_pvt_init(), test_item_alloc(), test_vm_api_create_mock_snapshot(), transmit_response_using_temp(), unbound_config_alloc(), update_odbc(), vm_msg_snapshot_alloc(), and xmpp_client_alloc().

ast_string_field_init_extended

#define ast_string_field_init_extended	(		x,
			field
	)

Initialize an extended string field.

Since

13.9.0

Parameters

x	Pointer to a structure containing the field
field	The extended field to initialize

Return values

zero	on success
non-zero	on 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 395 of file stringfields.h.

Referenced by AST_TEST_DEFINE().

ast_string_field_ptr_build

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

Set a field to a complex (built) value.

Parameters

x	Pointer to a structure containing fields
ptr	Pointer to a field within the structure
fmt	printf-style format string
args	Arguments for format string

Returns

nothing

Definition at line 531 of file stringfields.h.

ast_string_field_ptr_build_va

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

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

Parameters

x	Pointer to a structure containing fields
ptr	Pointer to a field within the structure
fmt	printf-style format string
args	Arguments for format string in va_list format

Returns

nothing

Definition at line 569 of file stringfields.h.

Referenced by ast_manager_event_blob_create().

ast_string_field_ptr_set

#define ast_string_field_ptr_set	(		x,
			ptr,
			data
	)

Set a field to a simple string value.

Parameters

x	Pointer to a structure containing fields
ptr	Pointer to a field within the structure
data	String value to be copied into the field

Return values

zero	on success
non-zero	on error

Definition at line 470 of file stringfields.h.

Referenced by ast_parse_digest(), and reply_digest().

ast_string_field_ptr_set_by_fields

#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__)

Definition at line 503 of file stringfields.h.

Referenced by AST_TEST_DEFINE(), and stringfield_handler_fn().

ast_string_field_set

#define ast_string_field_set	(		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

Return values

zero	on success
non-zero	on error

Definition at line 514 of file stringfields.h.

Referenced by __find_call(), __find_callno(), __sip_alloc(), __sip_subscribe_mwi_do(), acf_faxopt_write(), acf_retrieve_docs(), action_originate(), agent_cfg_alloc(), agent_login_channel_config(), agent_pvt_new(), alloc_artificial_auth(), alloc_header(), alloc_new_parking_lot(), alloc_queue(), aor_apply_outbound_proxy(), append_mailbox_mapping(), applicationmap_item_alloc(), 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_phoneprov_provider_register(), ast_register_application2(), ast_res_pjsip_find_or_create_contact_status(), ast_sip_location_create_contact(), AST_TEST_DEFINE(), ast_xml_doc_item_alloc(), ast_xmpp_client_config_alloc(), attended_transfer_properties_alloc(), authenticate_reply(), authenticate_request(), authenticate_verify(), base_process_parked_channel(), base_process_party_a(), bridge_base_init(), bridge_candidate_add_to_cdr(), bridge_config_set_limits_warning_values(), bridge_moh_create(), bridge_template_handler(), bucket_copy_handler(), bucket_file_copy_handler(), build_calendar(), build_config_docs(), build_peer(), build_profile(), build_route(), build_user(), cache_get_callno_locked(), caldav_add_event(), caldav_load_calendar(), calendar_write_exec(), cdr_all_relink(), cdr_all_unlink(), cdr_object_alloc(), cdr_object_create_and_append(), change_callid_pvt(), channel_snapshot_base_create(), channel_snapshot_caller_create(), channel_snapshot_dialplan_create(), check_access(), check_peer_ok(), check_user_full(), clone_parkinglot_cfg(), config_alloc(), contact_alloc(), copy_event_data(), copy_to_voicemail(), create_addr(), create_addr_from_peer(), create_dynamic_lot_full(), custom_prepare(), device_state_subscription_create(), dial_state_process_bridge_enter(), endelm(), endpoint_internal_create(), ewscal_load_calendar(), exchangecal_load_calendar(), extensionstate_update(), extract_uri(), fax_gateway_attach(), fax_gateway_detect_t38(), fax_gateway_framehook(), fax_gateway_start(), feature_attended_transfer(), featuregroup_handler(), featuremap_set(), fetch_access_token(), forked_invite_init(), format_log_message_ap(), from_user_handler(), general_set(), generate_test_parking_lot(), generic_fax_exec(), get_also_info(), get_destination(), get_pai(), get_realm(), get_refer_info(), get_rpid(), handle_bridge_enter(), handle_bridge_leave_message(), handle_cc_notify(), handle_incoming(), handle_local_optimization_end(), handle_masquerade(), handle_options(), handle_request_bye(), handle_request_invite(), handle_request_options(), handle_request_publish(), handle_request_refer(), handle_response(), handle_response_invite(), handle_response_notify(), handle_response_publish(), handle_response_register(), handle_response_subscribe(), handle_scan_file(), iax2_call(), iax2_request(), ical_load_calendar(), icalendar_add_event(), init_acf_query(), init_pvt(), init_queue(), initreqprep(), ip_identify_apply(), jingle_alloc(), jingle_endpoint_alloc(), jingle_interpret_description(), launch_monitor_thread(), load_config(), load_module(), msg_send_exec(), msg_set_var_full(), mwi_create_state(), new_iax(), new_outgoing(), new_realtime_sqlite3_db(), on_load_attestation(), on_load_ca_file(), on_load_ca_path(), on_load_path(), on_load_public_cert_url(), parking_lot_cfg_alloc(), parking_lot_cfg_remove_extensions(), parse_line(), parse_ok_contact(), parse_register_contact(), permanent_uri_handler(), pickup_set(), play_on_channel(), playback_create(), presence_state_alloc(), process_description_file(), process_sdp_o(), queue_set_param(), queue_stasis_data_alloc(), raise_exception(), receive_message(), receivefax_exec(), reg_source_db(), register_aor_core(), register_verify(), registry_authrequest(), reply_digest(), reqprep(), respprep(), save_osptoken(), sendfax_exec(), set_peer_defaults(), set_pvt_defaults(), set_sound(), setup_bridge_role_option(), single_state_process_bridge_enter(), sip_call(), sip_monitor_instance_init(), sip_msg_send(), sip_parse_register_line(), sip_poke_peer(), sip_register(), sip_reload(), sip_request_call(), sip_send_mwi_to_peer(), sip_sendtext(), sip_set_redirstr(), sip_subscribe_mwi(), skel_level_alloc(), sla_build_station(), sla_build_trunk(), socket_process_helper(), startelm(), stasis_app_bridge_playback_channel_add(), stasis_app_control_play_uri(), stasis_app_recording_options_create(), stasis_app_stored_recording_find_by_name(), store_callerid(), t30_phase_e_handler(), tds_load_module(), test_item_alloc(), test_stir_shaken_create_cert(), test_vm_api_create_mock_snapshot(), test_vm_api_destroy_mailbox_voicemails(), test_vm_api_test_setup(), test_vm_api_update_test_snapshots(), transmit_refer(), transmit_register(), transmit_response_using_temp(), transport_tls_file_handler(), update_realtime_sqlite3_db(), verify_default_parking_lot(), vm_msg_snapshot_create(), xfer_set(), and xmpp_client_alloc().

ast_string_fields_cmp

#define ast_string_fields_cmp	(		instance1,
			instance2
	)

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

Since

12

Parameters

instance1	The first instance of the structure to be compared
instance2	The second instance of the structure to be compared

Return values

zero	if all string fields are equal (does not compare non-string field data)
non-zero	if the values of the string fields differ

Definition at line 607 of file stringfields.h.

Referenced by AST_TEST_DEFINE().

ast_string_fields_copy

#define ast_string_fields_copy	(		copy,
			orig
	)

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

Since

12

Parameters

copy	The instance of the structure to be copied into
orig	The instance of the structure to be copied from

Return values

zero	on success
non-zero	on error

Definition at line 627 of file stringfields.h.

Referenced by AST_TEST_DEFINE(), bridge_features_limits_copy(), clone_parkinglot_cfg(), featuremap_copy(), general_copy(), pickup_copy(), sip_contact_status_copy(), and xfer_copy().

Typedef Documentation

ast_string_field

typedef const char* ast_string_field

Definition at line 190 of file stringfields.h.

ast_string_field_allocation

typedef uint16_t ast_string_field_allocation

Definition at line 194 of file stringfields.h.

Enumeration Type Documentation

ast_stringfield_cleanup_type

enum ast_stringfield_cleanup_type

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 309 of file stringfields.h.

                                  {
   /*!
    * 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_RESET = 0,
   /*!
    * 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.
    */
   AST_STRINGFIELD_DESTROY = -1,
};

Function Documentation

__ast_calloc_with_stringfields()

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
	)

Definition at line 380 of file stringfields.c.

References __ast_calloc(), __ast_string_field_empty, allocation, ast_assert, ast_free, AST_VECTOR_APPEND, AST_VECTOR_INIT, ast_string_field_mgr::embedded_pool, NULL, optimal_alloc_size(), pool, ast_string_field_pool::size, and ast_string_field_mgr::string_fields.

{
   struct ast_string_field_mgr *mgr;
   struct ast_string_field_pool *pool;
   struct ast_string_field_pool **pool_head;
   size_t pool_size_needed = sizeof(*pool) + pool_size;
   size_t size_to_alloc = optimal_alloc_size(struct_size + pool_size_needed);
   void *allocation;
   const char **p;
   size_t initial_vector_size;

   ast_assert(num_structs == 1);

   allocation = __ast_calloc(num_structs, size_to_alloc, file, lineno, func);
   if (!allocation) {
      return NULL;
   }

   mgr = allocation + field_mgr_offset;

   pool = allocation + struct_size;
   pool_head = allocation + field_mgr_pool_offset;
   p = (const char **) pool_head + 1;
   initial_vector_size = ((size_t) (((char *)mgr) - ((char *)p))) / sizeof(*p);

   if (AST_VECTOR_INIT(&mgr->string_fields, initial_vector_size)) {
      ast_free(allocation);
      return NULL;
   }

   while ((struct ast_string_field_mgr *) p != mgr) {
      AST_VECTOR_APPEND(&mgr->string_fields, p);
      *p++ = __ast_string_field_empty;
   }

   mgr->embedded_pool = pool;
   *pool_head = pool;
   pool->size = size_to_alloc - struct_size - sizeof(*pool);

   return allocation;
}

__ast_string_field_alloc_space()

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
	)

Definition at line 202 of file stringfields.c.

References add_string_pool(), ast_alignof, ast_assert, ast_make_room_for, AST_STRING_FIELD_ALLOCATION, ast_string_field_mgr::last_alloc, NULL, and result.

Referenced by __ast_string_field_ptr_build_va().

{
   char *result = NULL;
   size_t space = (*pool_head)->size - (*pool_head)->used;
   size_t to_alloc;

   /* Make room for ast_string_field_allocation and make it a multiple of that. */
   to_alloc = ast_make_room_for(needed, ast_string_field_allocation);
   ast_assert(to_alloc % ast_alignof(ast_string_field_allocation) == 0);

   if (__builtin_expect(to_alloc > space, 0)) {
      size_t new_size = (*pool_head)->size;

      while (new_size < to_alloc) {
         new_size *= 2;
      }

      if (add_string_pool(mgr, pool_head, new_size, file, lineno, func)) {
         return NULL;
      }
   }

   /* pool->base is always aligned (gcc aligned attribute). We ensure that
    * to_alloc is also a multiple of ast_alignof(ast_string_field_allocation)
    * causing result to always be aligned as well; which in turn fixes that
    * AST_STRING_FIELD_ALLOCATION(result) is aligned. */
   result = (*pool_head)->base + (*pool_head)->used;
   (*pool_head)->used += to_alloc;
   (*pool_head)->active += needed;
   result += ast_alignof(ast_string_field_allocation);
   AST_STRING_FIELD_ALLOCATION(result) = needed;
   mgr->last_alloc = result;

   return result;
}

__ast_string_field_free_memory()

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.

Definition at line 103 of file stringfields.c.

References ast_string_field_pool::active, ast_free, ast_log, AST_STRINGFIELD_DESTROY, AST_STRINGFIELD_RESET, AST_VECTOR_CALLBACK_VOID, AST_VECTOR_FREE, ast_string_field_mgr::embedded_pool, LOG_WARNING, NULL, ast_string_field_pool::prev, reset_field(), ast_string_field_mgr::string_fields, and ast_string_field_pool::used.

Referenced by __ast_string_field_init().

{
   struct ast_string_field_pool *cur = NULL;
   struct ast_string_field_pool *preserve = NULL;

   /* reset all the fields regardless of cleanup type */
   AST_VECTOR_CALLBACK_VOID(&mgr->string_fields, reset_field);

   switch (cleanup_type) {
   case AST_STRINGFIELD_DESTROY:
      AST_VECTOR_FREE(&mgr->string_fields);

      if (mgr->embedded_pool) { /* ALWAYS preserve the embedded pool if there is one */
         preserve = mgr->embedded_pool;
         preserve->used = preserve->active = 0;
      }

      break;
   case AST_STRINGFIELD_RESET:
      /* Preserve the embedded pool if there is one, otherwise the last pool */
      if (mgr->embedded_pool) {
         preserve = mgr->embedded_pool;
      } else {
         if (*pool_head == NULL) {
            ast_log(LOG_WARNING, "trying to reset empty pool\n");
            return -1;
         }
         preserve = *pool_head;
      }
      preserve->used = preserve->active = 0;
      break;
   default:
      return -1;
   }

   cur = *pool_head;
   while (cur) {
      struct ast_string_field_pool *prev = cur->prev;

      if (cur != preserve) {
         ast_free(cur);
      }
      cur = prev;
   }

   *pool_head = preserve;
   if (preserve) {
      preserve->prev = NULL;
   }

   return 0;
}

__ast_string_field_init()

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.

Definition at line 171 of file stringfields.c.

References __ast_string_field_empty, __ast_string_field_free_memory(), add_string_pool(), AST_VECTOR_APPEND, AST_VECTOR_FREE, AST_VECTOR_INIT, ast_string_field_mgr::embedded_pool, ast_string_field_mgr::last_alloc, NULL, and ast_string_field_mgr::string_fields.

{
   const char **p = (const char **) pool_head + 1;
   size_t initial_vector_size = ((size_t) (((char *)mgr) - ((char *)p))) / sizeof(*p);

   if (needed <= 0) {
      return __ast_string_field_free_memory(mgr, pool_head, needed, file, lineno, func);
   }

   mgr->last_alloc = NULL;

   if (AST_VECTOR_INIT(&mgr->string_fields, initial_vector_size)) {
      return -1;
   }

   while ((struct ast_string_field_mgr *) p != mgr) {
      AST_VECTOR_APPEND(&mgr->string_fields, p);
      *p++ = __ast_string_field_empty;
   }

   *pool_head = NULL;
   mgr->embedded_pool = NULL;
   if (add_string_pool(mgr, pool_head, needed, file, lineno, func)) {
      AST_VECTOR_FREE(&mgr->string_fields);
      return -1;
   }

   return 0;
}

__ast_string_field_ptr_build()

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,
			...
	)

Definition at line 369 of file stringfields.c.

References __ast_string_field_ptr_build_va().

{
   va_list ap;

   va_start(ap, format);
   __ast_string_field_ptr_build_va(mgr, pool_head, ptr, format, ap, file, lineno, func);
   va_end(ap);
}

__ast_string_field_ptr_build_va()

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
	)

Definition at line 286 of file stringfields.c.

References __ast_string_field_alloc_space(), __ast_string_field_empty, __ast_string_field_release_active(), ast_align_for, ast_alignof, ast_assert, ast_make_room_for, AST_STRING_FIELD_ALLOCATION, available(), grow(), and ast_string_field_mgr::last_alloc.

Referenced by __ast_string_field_ptr_build().

{
   size_t needed;
   size_t available;
   size_t space = (*pool_head)->size - (*pool_head)->used;
   int res;
   ssize_t grow;
   char *target;
   va_list ap2;

   /* if the field already has space allocated, try to reuse it;
      otherwise, try to use the empty space at the end of the current
      pool
   */
   if (*ptr != __ast_string_field_empty) {
      target = (char *) *ptr;
      available = AST_STRING_FIELD_ALLOCATION(*ptr);
      if (*ptr == mgr->last_alloc) {
         available += space;
      }
   } else {
      /* pool->used is always a multiple of ast_alignof(ast_string_field_allocation)
       * so we don't need to re-align anything here.
       */
      target = (*pool_head)->base + (*pool_head)->used + ast_alignof(ast_string_field_allocation);
      if (space > ast_alignof(ast_string_field_allocation)) {
         available = space - ast_alignof(ast_string_field_allocation);
      } else {
         available = 0;
      }
   }

   va_copy(ap2, ap);
   res = vsnprintf(target, available, format, ap2);
   va_end(ap2);

   if (res < 0) {
      /* Are we out of memory? */
      return;
   }
   if (res == 0) {
      __ast_string_field_release_active(*pool_head, *ptr);
      *ptr = __ast_string_field_empty;
      return;
   }
   needed = (size_t)res + 1; /* NUL byte */

   if (needed > available) {
      /* the allocation could not be satisfied using the field's current allocation
         (if it has one), or the space available in the pool (if it does not). allocate
         space for it, adding a new string pool if necessary.
      */
      target = (char *) __ast_string_field_alloc_space(mgr, pool_head, needed, file, lineno, func);
      if (!target) {
         return;
      }
      vsprintf(target, format, ap);
      va_end(ap); /* XXX va_end without va_start? */
      __ast_string_field_release_active(*pool_head, *ptr);
      *ptr = target;
   } else if (*ptr != target) {
      /* the allocation was satisfied using available space in the pool, but not
         using the space already allocated to the field
      */
      __ast_string_field_release_active(*pool_head, *ptr);
      mgr->last_alloc = *ptr = target;
           ast_assert(needed < (ast_string_field_allocation)-1);
      AST_STRING_FIELD_ALLOCATION(target) = (ast_string_field_allocation)needed;
      (*pool_head)->used += ast_make_room_for(needed, ast_string_field_allocation);
      (*pool_head)->active += needed;
   } else if ((grow = (needed - AST_STRING_FIELD_ALLOCATION(*ptr))) > 0) {
      /* the allocation was satisfied by using available space in the pool *and*
         the field was the last allocated field from the pool, so it grew
      */
      AST_STRING_FIELD_ALLOCATION(*ptr) += grow;
      (*pool_head)->used += ast_align_for(grow, ast_string_field_allocation);
      (*pool_head)->active += grow;
   }
}

__ast_string_field_ptr_grow()

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
	)

Definition at line 240 of file stringfields.c.

References AST_STRING_FIELD_ALLOCATION, grow(), and ast_string_field_mgr::last_alloc.

{
   ssize_t grow = needed - AST_STRING_FIELD_ALLOCATION(*ptr);
   size_t space = (*pool_head)->size - (*pool_head)->used;

   if (*ptr != mgr->last_alloc) {
      return 1;
   }

   if (space < grow) {
      return 1;
   }

   (*pool_head)->used += grow;
   (*pool_head)->active += grow;
   AST_STRING_FIELD_ALLOCATION(*ptr) += grow;

   return 0;
}

__ast_string_field_release_active()

void __ast_string_field_release_active	(	struct ast_string_field_pool *	pool_head,
		const ast_string_field	ptr
	)

Definition at line 261 of file stringfields.c.

References __ast_string_field_empty, ast_string_field_pool::active, ast_free, AST_STRING_FIELD_ALLOCATION, NULL, pool, and ast_string_field_pool::prev.

Referenced by __ast_string_field_ptr_build_va(), and __ast_string_fields_copy().

{
   struct ast_string_field_pool *pool, *prev;

   if (ptr == __ast_string_field_empty) {
      return;
   }

   for (pool = pool_head, prev = NULL; pool; prev = pool, pool = pool->prev) {
      if ((ptr >= pool->base) && (ptr <= (pool->base + pool->size))) {
         pool->active -= AST_STRING_FIELD_ALLOCATION(ptr);
         if (pool->active == 0) {
            if (prev) {
               prev->prev = pool->prev;
               ast_free(pool);
            } else {
               pool->used = 0;
            }
         }
         break;
      }
   }
}

__ast_string_fields_cmp()

int __ast_string_fields_cmp	(	struct ast_string_field_vector *	left,
		struct ast_string_field_vector *	right
	)

Definition at line 424 of file stringfields.c.

References ast_assert, AST_VECTOR_GET, and AST_VECTOR_SIZE.

{
   int i;
   int res = 0;

   ast_assert(AST_VECTOR_SIZE(left) == AST_VECTOR_SIZE(right));

   for (i = 0; i < AST_VECTOR_SIZE(left); i++) {
      if ((res = strcmp(*AST_VECTOR_GET(left, i), *AST_VECTOR_GET(right, i)))) {
         return res;
      }
   }

   return res;
}

__ast_string_fields_copy()

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
	)

Definition at line 441 of file stringfields.c.

References __ast_string_field_empty, __ast_string_field_ptr_set_by_fields, __ast_string_field_release_active(), ast_assert, AST_VECTOR_GET, AST_VECTOR_SIZE, and ast_string_field_mgr::string_fields.

{
   int i;
   struct ast_string_field_vector *dest = &(copy_mgr->string_fields);
   struct ast_string_field_vector *src = &(orig_mgr->string_fields);

   ast_assert(AST_VECTOR_SIZE(dest) == AST_VECTOR_SIZE(src));

   for (i = 0; i < AST_VECTOR_SIZE(dest); i++) {
      __ast_string_field_release_active(copy_pool, *AST_VECTOR_GET(dest, i));
      *AST_VECTOR_GET(dest, i) = __ast_string_field_empty;
   }

   for (i = 0; i < AST_VECTOR_SIZE(dest); i++) {
      if (__ast_string_field_ptr_set_by_fields(copy_pool, *copy_mgr, AST_VECTOR_GET(dest, i),
         *AST_VECTOR_GET(src, i), file, lineno, func)) {
         return -1;
      }
   }

   return 0;
}

AST_VECTOR()

AST_VECTOR	(	ast_string_field_vector	,
		const char **
	)

Variable Documentation

__ast_string_field_empty

const char* __ast_string_field_empty

Definition at line 43 of file stringfields.c.

Referenced by __ast_calloc_with_stringfields(), __ast_string_field_init(), __ast_string_field_ptr_build_va(), __ast_string_field_release_active(), __ast_string_fields_copy(), AST_TEST_DEFINE(), and reset_field().