Fri Aug 24 02:28:24 2007

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. Build a string in a buffer, designed to be called repeatedly.
 AST_INLINE_API (char *ast_skip_blanks(const char *str),{while(*str &&*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. Trims trailing whitespace characters from 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. s The string to be stripped (will be modified).

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 258 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_start(), ast_cdr_update(), ast_park_call(), ast_play_and_record_full(), ast_request_inherit(), ast_set_callerid(), ast_setstate(), asyncgoto_exec(), authenticate(), build_callid_pvt(), build_callid_registry(), build_rpid(), builtin_automonitor(), callerid_read(), cdr_pgsql_read_config(), check_auth(), check_post(), copy_message(), do_parking_thread(), fast_originate(), find_conf(), forward_message(), get_also_info(), get_cid_name(), 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_exec(), pbx_builtin_execiftime(), pbx_load_config(), pgsql_reconnect(), play_mailbox_owner(), post_cdr(), post_manager_event(), process_sdp(), queue_exec(), realtime_common(), realtime_exec(), register_peer_exten(), return_exec(), 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))   ) 

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

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 913 of file utils.c.

References result.

Referenced by ast_build_string().

00914 {
00915    int result;
00916 
00917    if (!buffer || !*buffer || !space || !*space)
00918       return -1;
00919 
00920    result = vsnprintf(*buffer, *space, fmt, ap);
00921 
00922    if (result < 0)
00923       return -1;
00924    else if (result > *space)
00925       result = *space;
00926 
00927    *buffer += result;
00928    *space -= result;
00929    return 0;
00930 }

int ast_false ( const char *  val  ) 

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 961 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(), and strings_to_mask().

00962 {
00963    if (ast_strlen_zero(s))
00964       return 0;
00965 
00966    /* Determine if this is a false value */
00967    if (!strcasecmp(s, "no") ||
00968        !strcasecmp(s, "false") ||
00969        !strcasecmp(s, "n") ||
00970        !strcasecmp(s, "f") ||
00971        !strcasecmp(s, "0") ||
00972        !strcasecmp(s, "off"))
00973       return -1;
00974 
00975    return 0;
00976 }

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

get values from config variables.

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

01199 {
01200    long t;
01201    int scanned;
01202 
01203    if (dst == NULL)
01204       return -1;
01205 
01206    *dst = _default;
01207 
01208    if (ast_strlen_zero(src))
01209       return -1;
01210 
01211    /* only integer at the moment, but one day we could accept more formats */
01212    if (sscanf(src, "%ld%n", &t, &scanned) == 1) {
01213       *dst = t;
01214       if (consumed)
01215          *consumed = scanned;
01216       return 0;
01217    } else
01218       return -1;
01219 }

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

Size-limited null-terminating string copy. 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_blanks(const char *str)  ) 

Gets a pointer to the first non-whitespace character in a string. 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 1069 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().

01070 {
01071    int x, ofs = 0;
01072    const char *src;
01073 
01074    /* Join words into a string */
01075    if (!s)
01076       return;
01077    for (x = 0; ofs < len && w[x]; x++) {
01078       if (x > 0)
01079          s[ofs++] = ' ';
01080       for (src = w[x]; *src && ofs < len; src++)
01081          s[ofs++] = *src;
01082    }
01083    if (ofs == len)
01084       ofs--;
01085    s[ofs] = '\0';
01086 }

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 277 of file strings.h.

Referenced by peer_hash_cb(), and user_hash_cb().

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

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_http_load(), __ast_read(), __ast_request_and_dial(), __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_command(), action_extensionstate(), action_getconfig(), action_getvar(), action_hangup(), action_listcommands(), action_mailboxcount(), action_mailboxstatus(), 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_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_getvar(), ast_cdr_getvar_internal(), ast_cdr_init(), ast_cdr_merge(), ast_cdr_noanswer(), ast_cdr_serialize_variables(), 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_time_t(), ast_httpd_helper_thread(), ast_iax2_new(), ast_is_valid_string(), ast_jb_read_conf(), ast_linear_stream(), ast_localtime(), ast_log(), ast_makesocket(), ast_mktime(), ast_module_check(), ast_monitor_change_fname(), ast_monitor_start(), ast_monitor_stop(), ast_park_call(), ast_parseable_goto(), ast_pbx_outgoing_app(), ast_pbx_outgoing_exten(), ast_privacy_set(), ast_remotecontrol(), ast_stream_and_wait(), ast_true(), 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(), background_detect_exec(), base64_decode(), base64_encode(), begin_dial(), build_contact(), build_device(), build_gateway(), build_mapping(), build_peer(), build_reply_digest(), build_route(), build_rpid(), build_user(), builtin_automonitor(), 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(), check_access(), check_auth(), 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(), csv_log(), custom_log(), custom_prepare(), database_increment(), deltree_exec(), destroy_endpoint(), destroy_station(), destroy_trans(), destroy_trunk(), dial_trunk(), dialout(), dictate_exec(), directory_exec(), disa_exec(), do_directory(), do_immediate_setup(), do_message(), 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(), find_call(), 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_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_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_show_cache(), iax2_show_peer(), iax2_show_users(), iax_check_version(), iax_firmware_append(), iax_provflags2str(), ices_exec(), iftime(), inboxcount(), init_acf_query(), initreqprep(), isAnsweringMachine(), jb_choose_impl(), launch_monitor_thread(), launch_netscript(), leave_voicemail(), load_config(), load_moh_classes(), local_ast_moh_start(), log_events(), log_exec(), lookupblacklist_exec(), loopback_subst(), 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(), misdn_answer(), misdn_call(), misdn_check_l2l1(), misdn_facility_exec(), misdn_request(), misdn_set_opt_exec(), mixmonitor_exec(), mkintf(), moh2_exec(), morsecode_exec(), mp3_exec(), mysql_reconnect(), nbs_alloc(), notify_new_message(), nv_background_detect_exec(), nv_detectfax_exec(), 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_exec(), parkandannounce_exec(), parse(), parse_dial_string(), parse_register_contact(), parse_request(), parse_sip_options(), pbx_builtin_answer(), pbx_builtin_background(), pbx_builtin_busy(), pbx_builtin_congestion(), 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(), phone_call(), phone_new(), pickup_exec(), play_mailbox_owner(), play_message_callerid(), play_message_category(), play_message_datetime(), playback_exec(), pqm_exec(), 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_mysql(), realtime_multi_odbc(), realtime_multi_pgsql(), realtime_mysql(), realtime_odbc(), realtime_pgsql(), realtime_update_exec(), realtime_update_peer(), receive_ademco_contact_id(), record_exec(), register_peer_exten(), register_verify(), registry_rerequest(), reload_config(), reload_followme(), reload_queue_members(), reload_queues(), reply_digest(), reqprep(), respprep(), retrydial_exec(), return_exec(), 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(), shell_helper(), 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_check_device(), sla_queue_event_conf(), sla_ring_station(), sla_station_exec(), socket_process(), softhangup_exec(), spawn_mp3(), speech_background(), split_ext(), srv_callback(), 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_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  ) 

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 944 of file utils.c.

References ast_strlen_zero().

Referenced by __ast_http_load(), __login_exec(), _parse(), action_agent_callback_login(), action_agent_logoff(), action_originate(), action_setcdruserfield(), action_updateconfig(), aji_create_client(), aji_load_config(), apply_option(), apply_outgoing(), ast_jb_read_conf(), 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(), start_monitor_action(), strings_to_mask(), and update_common_options().

00945 {
00946    if (ast_strlen_zero(s))
00947       return 0;
00948 
00949    /* Determine if this is a true value */
00950    if (!strcasecmp(s, "yes") ||
00951        !strcasecmp(s, "true") ||
00952        !strcasecmp(s, "y") ||
00953        !strcasecmp(s, "t") ||
00954        !strcasecmp(s, "1") ||
00955        !strcasecmp(s, "on"))
00956       return -1;
00957 
00958    return 0;
00959 }

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 898 of file utils.c.

Referenced by sip_notify().

00899 {
00900    char *e;
00901    char *work = s;
00902 
00903    while ((e = strchr(work, ';'))) {
00904       if ((e > work) && (*(e-1) == '\\')) {
00905          memmove(e - 1, e, strlen(e) + 1);
00906          work = e;
00907       }
00908    }
00909 
00910    return s;
00911 }


Variable Documentation

size_t const char* fmt

Definition at line 195 of file strings.h.

size_t* space

Definition at line 195 of file strings.h.

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


Generated on Fri Aug 24 02:28:30 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1