Thu Oct 8 21:57:58 2009

Asterisk developer's documentation


strings.h File Reference

String manipulation functions. More...

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

Include dependency graph for strings.h:

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

Go to the source code of this file.

Data Structures

struct  ast_realloca

Defines

#define ast_restrdupa(ra, s)
#define S_OR(a, b)   (!ast_strlen_zero(a) ? (a) : (b))
 returns the equivalent of logic or for strings: first one if not empty, otherwise second one.

Functions

size_t const char __attribute__ ((format(printf, 3, 4)))
int ast_build_string_va (char **buffer, size_t *space, const char *fmt, va_list ap)
 Build a string in a buffer, designed to be called repeatedly.
int ast_false (const char *val)
int ast_get_time_t (const char *src, time_t *dst, time_t _default, int *consumed)
 get values from config variables.
 AST_INLINE_API (void ast_copy_string(char *dst, const char *src, size_t size),{while(*src &&size){*dst++=*src++;size--;}if(__builtin_expect(!size, 0)) dst--;*dst= '\0';}) int ast_build_string(char **buffer
 Size-limited null-terminating string copy.
 AST_INLINE_API (char *ast_skip_blanks(const char *str),{while(*str &&((unsigned char)*str)< 33) str++;return(char *) str;}) AST_INLINE_API(char *ast_trim_blanks(char *str)
 Gets a pointer to the first non-whitespace character in a string.
void ast_join (char *s, size_t len, char *const w[])
static force_inline int ast_str_hash (const char *str)
 Compute a hash value on a string.
static force_inline int ast_strlen_zero (const char *s)
int ast_true (const char *val)
char * ast_unescape_semicolon (char *s)
 Strip backslash for "escaped" semicolons.

Variables

size_t const char * fmt
size_t * space


Detailed Description

String manipulation functions.

Definition in file strings.h.


Define Documentation

#define ast_restrdupa ( ra,
 ) 

Definition at line 256 of file strings.h.

#define S_OR ( a,
 )     (!ast_strlen_zero(a) ? (a) : (b))

returns the equivalent of logic or for strings: first one if not empty, otherwise second one.

Definition at line 42 of file strings.h.

Referenced by __ast_cli_register(), __login_exec(), __sip_show_channels(), _sip_show_peer(), acf_if(), action_agents(), action_command(), action_setvar(), action_status(), agent_hangup(), aji_client_initialize(), aji_component_initialize(), aji_test(), allow_multiple_login(), app_exec(), ast_async_goto(), ast_cdr_end(), ast_cdr_free(), ast_cdr_init(), ast_cdr_setapp(), ast_cdr_start(), ast_cdr_update(), ast_channel_alloc(), ast_play_and_record_full(), ast_set_callerid(), ast_setstate_and_callerid(), asyncgoto_exec(), authenticate(), build_callid_pvt(), build_callid_registry(), build_rpid(), builtin_automonitor(), callerid_read(), check_auth(), check_post(), conf_run(), copy_message(), do_parking_thread(), fast_originate(), find_conf(), forward_message(), get_also_info(), get_cid_name(), get_destination(), get_refer_info(), handle_chanlist(), handle_chanlist_deprecated(), handle_request_invite(), handle_showchan(), handle_showchan_deprecated(), help1(), iax2_show_channels(), initreqprep(), join_queue(), leave_voicemail(), manager_dbput(), manager_parking_status(), manager_queues_status(), meetme_cmd(), moh_classes_show(), park_call_full(), park_exec(), pbx_builtin_execiftime(), pbx_exec(), pbx_load_config(), pgsql_reconnect(), play_mailbox_owner(), post_cdr(), post_manager_event(), process_sdp(), queue_exec(), realtime_common(), realtime_exec(), register_peer_exten(), senddialevent(), serialize_showchan(), set_one_cid(), setup_env(), sip_show_domains(), sip_show_settings(), sipsock_read(), skinny_answer(), skinny_hold(), skinny_indicate(), sla_show_stations(), sla_show_trunks(), socket_process(), transmit_notify_with_mwi(), update_realtime_members(), wait_for_answer(), zt_handle_dtmfup(), zt_handle_event(), zt_hangup(), and zt_read().


Function Documentation

size_t const char __attribute__ ( (format(printf, 3, 4))   ) 

External routines may send asterisk manager events this way

Parameters:
category Event category, matches manager authorization
event Event name
contents Contents of event
Type Constraints

int ast_build_string_va ( char **  buffer,
size_t *  space,
const char *  fmt,
va_list  ap 
)

Build a string in a buffer, designed to be called repeatedly.

This is a wrapper for snprintf, that properly handles the buffer pointer and buffer space available.

Returns:
0 on success, non-zero on failure.
Parameters:
buffer current position in buffer to place string into (will be updated on return)
space remaining space in buffer (will be updated on return)
fmt printf-style format string
ap varargs list of arguments for format

Definition at line 1020 of file utils.c.

Referenced by ast_build_string().

01021 {
01022    int result;
01023 
01024    if (!buffer || !*buffer || !space || !*space)
01025       return -1;
01026 
01027    result = vsnprintf(*buffer, *space, fmt, ap);
01028 
01029    if (result < 0)
01030       return -1;
01031    else if (result > *space)
01032       result = *space;
01033 
01034    *buffer += result;
01035    *space -= result;
01036    return 0;
01037 }

int ast_false ( const char *  val  ) 

Make sure something is false

Determine if a string containing a boolean value is "false". This function checks to see whether a string passed to it is an indication of an "false" value. It checks to see if the string is "no", "false", "n", "f", "off" or "0".

Returns 0 if val is a NULL pointer, -1 if "false", and 0 otherwise.

Definition at line 1068 of file utils.c.

References ast_strlen_zero().

Referenced by aji_create_client(), aji_load_config(), ast_rtp_reload(), ast_udptl_reload(), handle_common_options(), init_acf_query(), load_config(), load_odbc_config(), reload(), run_agi(), set_insecure_flags(), sla_build_trunk(), and strings_to_mask().

01069 {
01070    if (ast_strlen_zero(s))
01071       return 0;
01072 
01073    /* Determine if this is a false value */
01074    if (!strcasecmp(s, "no") ||
01075        !strcasecmp(s, "false") ||
01076        !strcasecmp(s, "n") ||
01077        !strcasecmp(s, "f") ||
01078        !strcasecmp(s, "0") ||
01079        !strcasecmp(s, "off"))
01080       return -1;
01081 
01082    return 0;
01083 }

int ast_get_time_t ( const char *  src,
time_t *  dst,
time_t  _default,
int *  consumed 
)

get values from config variables.

Definition at line 1305 of file utils.c.

References ast_strlen_zero(), and t.

Referenced by acf_strftime(), build_peer(), cache_lookup_internal(), handle_saydatetime(), load_password(), play_message_datetime(), realtime_peer(), and sayunixtime_exec().

01306 {
01307    long t;
01308    int scanned;
01309 
01310    if (dst == NULL)
01311       return -1;
01312 
01313    *dst = _default;
01314 
01315    if (ast_strlen_zero(src))
01316       return -1;
01317 
01318    /* only integer at the moment, but one day we could accept more formats */
01319    if (sscanf(src, "%ld%n", &t, &scanned) == 1) {
01320       *dst = t;
01321       if (consumed)
01322          *consumed = scanned;
01323       return 0;
01324    } else
01325       return -1;
01326 }

AST_INLINE_API ( void   ast_copy_stringchar *dst, const char *src, size_t size  ) 

Size-limited null-terminating string copy.

Parameters:
ast_copy_string function being used
dst The destination buffer.
src The source string
size The size of the destination buffer
Returns:
Nothing.
This is similar to strncpy, with two important differences:
  • the destination buffer will always be null-terminated
  • the destination buffer is not filled with zeros past the copied string length These differences make it slightly more efficient, and safer to use since it will not leave the destination buffer unterminated. There is no need to pass an artificially reduced buffer size to this function (unlike strncpy), and the buffer does not need to be initialized to zeroes prior to calling this function.

Build a string in a buffer, designed to be called repeatedly This is a wrapper for snprintf, that properly handles the buffer pointer and buffer space available.

Parameters:
buffer current position in buffer to place string into (will be updated on return)
space remaining space in buffer (will be updated on return)
fmt printf-style format string
Returns:
0 on success, non-zero on failure.

AST_INLINE_API ( char *  ast_skip_blanksconst char *str  ) 

Gets a pointer to the first non-whitespace character in a string.

Parameters:
ast_skip_blanks function being used
str the input string
Returns:
a pointer to the first non-whitespace character
Trims trailing whitespace characters from a string.
Parameters:
ast_trim_blanks function being used
str the input string
Returns:
a pointer to the modified string

void ast_join ( char *  s,
size_t  len,
char *const   w[] 
)

Definition at line 1176 of file utils.c.

Referenced by __ast_cli_generator(), __ast_cli_register(), ast_builtins_init(), console_sendtext(), console_sendtext_deprecated(), find_best(), handle_agidumphtml(), handle_help(), handle_showagi(), help1(), and help_workhorse().

01177 {
01178    int x, ofs = 0;
01179    const char *src;
01180 
01181    /* Join words into a string */
01182    if (!s)
01183       return;
01184    for (x = 0; ofs < len && w[x]; x++) {
01185       if (x > 0)
01186          s[ofs++] = ' ';
01187       for (src = w[x]; *src && ofs < len; src++)
01188          s[ofs++] = *src;
01189    }
01190    if (ofs == len)
01191       ofs--;
01192    s[ofs] = '\0';
01193 }

static force_inline int ast_str_hash ( const char *  str  )  [static]

Compute a hash value on a string.

This famous hash algorithm was written by Dan Bernstein and is commonly used.

http://www.cse.yorku.ca/~oz/hash.html

Definition at line 275 of file strings.h.

Referenced by peer_hash_cb(), and user_hash_cb().

00276 {
00277    int hash = 5381;
00278 
00279    while (*str)
00280       hash = hash * 33 ^ *str++;
00281 
00282    return abs(hash);
00283 }

static force_inline int ast_strlen_zero ( const char *  s  )  [static]

Definition at line 34 of file strings.h.

Referenced by __ast_callerid_generate(), __ast_cli_generator(), __ast_device_state_changed_literal(), __ast_http_load(), __ast_pbx_run(), __ast_read(), __ast_request_and_dial_uniqueid(), __has_voicemail(), __iax2_show_peers(), __login_exec(), __oh323_new(), _macro_exec(), _sip_show_peer(), _sip_show_peers(), _while_exec(), acf_channel_read(), acf_curl_exec(), acf_if(), acf_rand_exec(), acf_strptime(), acf_vmcount_exec(), action_agent_callback_login(), action_agent_logoff(), action_agents(), action_bridge(), action_command(), action_devstate(), action_extensionstate(), action_getconfig(), action_getvar(), action_hangup(), action_listcommands(), action_mailboxcount(), action_mailboxstatus(), action_message(), action_originate(), action_redirect(), action_setcdruserfield(), action_setvar(), action_status(), action_timeout(), action_transfer(), action_transferhangup(), action_updateconfig(), action_waitevent(), action_zapdialoffhook(), action_zapdndoff(), action_zapdndon(), action_zapshowchannels(), add_agent(), add_realm_authentication(), add_sip_domain(), admin_exec(), adsi_exec(), adsi_message(), advanced_options(), agent_call(), agent_devicestate(), agent_hangup(), agent_logoff_maintenance(), agent_new(), agent_read(), agent_request(), agents_show(), agents_show_online(), agi_exec_full(), alarmreceiver_exec(), alsa_new(), answer_exec_enable(), app_exec(), append_mailbox_mapping(), append_transaction(), apply_options_full(), apply_outgoing(), apply_peer(), aqm_exec(), ast_app_group_get_count(), ast_app_group_match_get_count(), ast_app_group_set_channel(), ast_app_group_split_group(), ast_bridge_call(), ast_build_timing(), ast_cdr_copy_vars(), ast_cdr_fork(), ast_cdr_getvar(), ast_cdr_getvar_internal(), ast_cdr_merge(), ast_cdr_noanswer(), ast_cdr_serialize_variables(), ast_channel_alloc(), ast_channel_bridge(), ast_cli_complete(), ast_db_gettree(), ast_dnsmgr_get(), ast_dnsmgr_lookup(), ast_explicit_goto(), ast_false(), ast_feature_interpret(), ast_frame_dump(), ast_get_group(), ast_get_time_t(), ast_httpd_helper_thread(), ast_iax2_new(), ast_is_valid_string(), ast_jb_read_conf(), ast_linear_stream(), ast_log(), ast_makesocket(), ast_monitor_change_fname(), ast_monitor_start(), ast_monitor_stop(), ast_parseable_goto(), ast_pbx_outgoing_app_uniqueid(), ast_pbx_outgoing_exten_uniqueid(), ast_privacy_set(), ast_remotecontrol(), ast_stream_and_wait(), ast_true(), ast_tzset(), ast_variable_delete(), ast_variable_update(), astman_get_variables(), astman_send_error(), astman_send_response(), async_wait(), asyncgoto_exec(), attempt_thread(), auth_exec(), authenticate(), authenticate_reply(), authenticate_verify(), authority_to_str(), autoanswer_complete(), autoanswer_exec(), background_detect_exec(), base64_decode(), base64_encode(), begin_dial(), bridge_exec(), build_contact(), build_device(), build_gateway(), build_mapping(), build_peer(), build_reply_digest(), build_route(), build_rpid(), build_user(), builtin_automonitor(), cache_get_callno_locked(), callerid_feed(), callerid_genmsg(), cb_events(), cdr_read(), cdr_write(), chan_misdn_log(), chanavail_exec(), change_monitor_action(), change_password_realtime(), channel_spy(), chanspy_exec(), chanspychan_exec(), check_access(), check_auth(), check_blacklist(), check_day(), check_dow(), check_goto_on_transfer(), check_month(), check_sip_domain(), check_timerange(), check_user_full(), checkmd5(), cli_audio_convert(), cli_audio_convert_deprecated(), compile_script(), conf_exec(), conf_run(), config_text_file_load(), console_dial(), console_dial_deprecated(), console_sendtext(), console_sendtext_deprecated(), controlplayback_exec(), copy_all_header(), copy_header(), copy_via_headers(), count_exec(), create_addr(), create_addr_from_peer(), create_dirpath(), create_queue_member(), csv_log(), custom_log(), custom_prepare(), database_increment(), deltree_exec(), destroy_endpoint(), destroy_station(), destroy_trans(), destroy_trunk(), devstate_write(), dial_trunk(), dialout(), dictate_exec(), directory_exec(), disa_exec(), do_directory(), do_immediate_setup(), do_message(), do_monitor(), do_parking_thread(), does_peer_need_mwi(), dump_agents(), dumpchan_exec(), dundi_exec(), dundi_flags2str(), dundi_helper(), dundi_hint2str(), dundi_lookup_local(), dundi_query_thread(), dundi_show_mappings(), dundi_show_peer(), dundifunc_read(), enum_callback(), env_write(), extenspy_exec(), extract_uri(), fast_originate(), feature_exec_app(), festival_exec(), fileexists_core(), find_call(), find_queue_by_name_rt(), find_sdp(), find_sip_method(), forkcdr_exec(), forward_message(), func_check_sipdomain(), func_header_read(), function_agent(), function_db_delete(), function_db_exists(), function_db_read(), function_db_write(), function_enum(), function_eval(), function_fieldqty(), function_realtime_read(), function_realtime_write(), function_txtcidname(), get_also_info(), get_destination(), get_range(), get_rdnis(), get_refer_info(), get_sip_pvt_byid_locked(), get_timerange(), gosub_exec(), gosubif_exec(), group_count_function_read(), group_function_read(), group_function_write(), group_list_function_read(), group_match_count_function_read(), group_show_channels(), gtalk_create_candidates(), gtalk_new(), handle_chanlist(), handle_chanlist_deprecated(), handle_command_response(), handle_controlstreamfile(), handle_getvariable(), handle_orig(), handle_request(), handle_request_bye(), handle_request_info(), handle_request_invite(), handle_request_options(), handle_request_refer(), handle_request_subscribe(), handle_response(), handle_response_refer(), handle_response_register(), handle_save_dialplan(), handle_saydatetime(), handle_show_dialplan(), handle_stimulus_message(), handle_updates(), handle_uri(), handle_voicemail_show_users(), hasvoicemail_exec(), iax2_call(), iax2_datetime(), iax2_devicestate(), iax2_prov_app(), iax2_request(), iax2_show_cache(), iax2_show_peer(), iax2_show_users(), iax_check_version(), iax_firmware_append(), iax_provflags2str(), ices_exec(), iftime(), inboxcount(), init_acf_query(), initreqprep(), inspect_module(), isAnsweringMachine(), jb_choose_impl(), launch_monitor_thread(), launch_netscript(), leave_voicemail(), load_config(), load_moh_classes(), load_odbc_config(), local_ast_moh_start(), log_events(), log_exec(), lookupblacklist_exec(), loopback_parse(), main(), make_email_file(), make_filename(), make_logchannel(), manager_add_queue_member(), manager_dbget(), manager_dbput(), manager_iax2_show_peers(), manager_jabber_send(), manager_park(), manager_parking_status(), manager_pause_queue_member(), manager_queues_status(), manager_remove_queue_member(), manager_sip_show_peer(), manager_sip_show_peers(), matchcid(), math(), md5(), meetmemute(), mgcp_call(), mgcp_hangup(), mgcp_new(), mgcp_request(), mgcp_ss(), mgcpsock_read(), milliwatt_exec(), misdn_answer(), misdn_call(), misdn_cfg_update_ptp(), misdn_check_l2l1(), misdn_facility_exec(), misdn_overlap_dial_task(), misdn_request(), misdn_set_opt_exec(), mixmonitor_exec(), mkintf(), moh2_exec(), morsecode_exec(), mp3_exec(), nbs_alloc(), notify_new_message(), oh323_call(), oh323_request(), onedigit_goto(), orig_app(), orig_exten(), osp_auth(), ospauth_exec(), ospfinished_exec(), osplookup_exec(), ospnext_exec(), oss_new(), page_exec(), park_call_full(), park_exec(), parkandannounce_exec(), parse(), parse_config(), parse_cookies(), parse_dial_string(), parse_register_contact(), parse_request(), parse_sip_options(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_execiftime(), pbx_builtin_gotoif(), pbx_builtin_gotoiftime(), pbx_builtin_hangup(), pbx_builtin_importvar(), pbx_builtin_resetcdr(), pbx_builtin_saynumber(), pbx_builtin_setglobalvar(), pbx_builtin_setvar(), pbx_builtin_waitexten(), pbx_checkcondition(), pbx_load_users(), pbx_substitute_variables_helper_full(), pgsql_reconnect(), phone_call(), phone_new(), pickup_exec(), play_mailbox_owner(), play_message_callerid(), play_message_category(), play_message_datetime(), playback_exec(), post_cdr(), pqm_exec(), print_ext(), privacy_exec(), process_ast_dsp(), process_message(), process_my_load_module(), process_sdp(), process_text_line(), process_token(), process_zap(), ql_exec(), queue_exec(), queue_function_qac(), queue_function_queuememberlist(), queue_function_queuewaitingcount(), quit_handler(), random_exec(), read_agent_config(), read_config(), read_exec(), readfile_exec(), real_ctx(), realtime_exec(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_odbc(), realtime_pgsql(), realtime_pgsql_status(), realtime_update_exec(), realtime_update_peer(), receive_ademco_contact_id(), record_exec(), register_peer_exten(), register_verify(), registry_rerequest(), reload(), reload_config(), reload_followme(), reload_queue_members(), reload_queues(), reply_digest(), reqprep(), respprep(), retrydial_exec(), return_exec(), ring_entry(), rpt_exec(), rqm_exec(), run_agi(), run_externnotify(), senddtmf_exec(), sendimage_exec(), sendmail(), sendtext_exec(), sendurl_exec(), set(), set_agentbycallerid(), set_config(), set_insecure_flags(), set_member_paused(), set_one_cid(), setcallerid_exec(), setup_incoming_call(), setup_zap(), sha1(), sip_addheader(), sip_hangup(), sip_new(), sip_poke_peer(), sip_register(), sip_request_call(), sip_sendtext(), sip_show_channel(), sip_show_user(), sip_sipredirect(), skel_exec(), skinny_hold(), skinny_new(), skinny_register(), skinny_request(), skinny_ss(), sla_build_station(), sla_build_trunk(), sla_check_device(), sla_queue_event_conf(), sla_ring_station(), sla_station_exec(), smdi_msg_read(), smdi_msg_retrieve_read(), socket_process(), softhangup_exec(), spawn_mp3(), speech_background(), split_ext(), ss_thread(), start_monitor_action(), start_monitor_exec(), static_callback(), stop_monitor_action(), store_config(), strings_to_mask(), system_exec_helper(), testclient_exec(), testserver_exec(), transfer_exec(), transmit_invite(), transmit_modify_request(), transmit_modify_with_sdp(), transmit_notify_request(), transmit_notify_request_with_callerid(), transmit_refer(), transmit_register(), transmit_request_with_auth(), try_calling(), try_firmware(), unalloc_sub(), update_call_counter(), update_realtime_member_field(), update_registry(), upqm_exec(), uridecode(), uriencode(), userevent_exec(), valid_exit(), vm_authenticate(), vm_box_exists(), vm_exec(), vm_execmain(), vm_newuser(), vm_options(), vmauthenticate(), vmu_tm(), wait_for_answer(), wait_for_hangup(), wait_for_winner(), zapateller_exec(), zt_call(), zt_handle_event(), zt_hangup(), and zt_new().

00035 {
00036    return (!s || (*s == '\0'));
00037 }

int ast_true ( const char *  val  ) 

Make sure something is true

Determine if a string containing a boolean value is "true". This function checks to see whether a string passed to it is an indication of an "true" value. It checks to see if the string is "yes", "true", "y", "t", "on" or "1".

Returns 0 if val is a NULL pointer, -1 if "true", and 0 otherwise.

Definition at line 1051 of file utils.c.

References ast_strlen_zero().

Referenced by __ast_http_load(), __login_exec(), _parse(), action_agent_callback_login(), action_agent_logoff(), action_bridge(), action_originate(), action_setcdruserfield(), action_updateconfig(), aji_create_client(), aji_load_config(), apply_option(), apply_outgoing(), ast_jb_read_conf(), ast_readconfig(), authenticate(), build_device(), build_gateway(), build_peer(), build_user(), connect_link(), do_directory(), do_reload(), festival_exec(), get_encrypt_methods(), gtalk_load_config(), handle_common_options(), handle_save_dialplan(), init_logger_chain(), init_manager(), load_config(), load_module(), load_modules(), load_moh_classes(), load_odbc_config(), load_rpt_vars(), loadconfigurationfile(), manager_add_queue_member(), manager_pause_queue_member(), odbc_load_module(), osp_load(), parse_config(), pbx_load_config(), pbx_load_users(), process_zap(), queue_set_param(), read_agent_config(), reload(), reload_config(), reload_queues(), set_config(), set_insecure_flags(), sla_load_config(), smdi_load(), start_monitor_action(), strings_to_mask(), and update_common_options().

01052 {
01053    if (ast_strlen_zero(s))
01054       return 0;
01055 
01056    /* Determine if this is a true value */
01057    if (!strcasecmp(s, "yes") ||
01058        !strcasecmp(s, "true") ||
01059        !strcasecmp(s, "y") ||
01060        !strcasecmp(s, "t") ||
01061        !strcasecmp(s, "1") ||
01062        !strcasecmp(s, "on"))
01063       return -1;
01064 
01065    return 0;
01066 }

char* ast_unescape_semicolon ( char *  s  ) 

Strip backslash for "escaped" semicolons.

s The string to be stripped (will be modified).

Returns:
The stripped string.

Definition at line 1003 of file utils.c.

Referenced by sip_notify().

01004 {
01005    char *e;
01006    char *work = s;
01007 
01008    while ((e = strchr(work, ';'))) {
01009       if ((e > work) && (*(e-1) == '\\')) {
01010          memmove(e - 1, e, strlen(e) + 1);
01011          work = e;
01012       } else {
01013          work = e + 1;
01014       }
01015    }
01016 
01017    return s;
01018 }


Variable Documentation

size_t const char* fmt

Definition at line 193 of file strings.h.

size_t* space

Definition at line 193 of file strings.h.

Referenced by ast_tos2str(), dundi_decrypt(), phone_write_buf(), and rpt_master().


Generated on Thu Oct 8 21:57:58 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.8