Sat Apr 12 07:12:56 2008

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_start(), ast_cdr_update(), ast_channel_alloc(), ast_play_and_record_full(), ast_set_callerid(), ast_setstate_and_cid(), 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_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 977 of file utils.c.

Referenced by ast_build_string().

00978 {
00979    int result;
00980 
00981    if (!buffer || !*buffer || !space || !*space)
00982       return -1;
00983 
00984    result = vsnprintf(*buffer, *space, fmt, ap);
00985 
00986    if (result < 0)
00987       return -1;
00988    else if (result > *space)
00989       result = *space;
00990 
00991    *buffer += result;
00992    *space -= result;
00993    return 0;
00994 }

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 1025 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().

01026 {
01027    if (ast_strlen_zero(s))
01028       return 0;
01029 
01030    /* Determine if this is a false value */
01031    if (!strcasecmp(s, "no") ||
01032        !strcasecmp(s, "false") ||
01033        !strcasecmp(s, "n") ||
01034        !strcasecmp(s, "f") ||
01035        !strcasecmp(s, "0") ||
01036        !strcasecmp(s, "off"))
01037       return -1;
01038 
01039    return 0;
01040 }

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

get values from config variables.

Definition at line 1262 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().

01263 {
01264    long t;
01265    int scanned;
01266 
01267    if (dst == NULL)
01268       return -1;
01269 
01270    *dst = _default;
01271 
01272    if (ast_strlen_zero(src))
01273       return -1;
01274 
01275    /* only integer at the moment, but one day we could accept more formats */
01276    if (sscanf(src, "%ld%n", &t, &scanned) == 1) {
01277       *dst = t;
01278       if (consumed)
01279          *consumed = scanned;
01280       return 0;
01281    } else
01282       return -1;
01283 }

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 1133 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().

01134 {
01135    int x, ofs = 0;
01136    const char *src;
01137 
01138    /* Join words into a string */
01139    if (!s)
01140       return;
01141    for (x = 0; ofs < len && w[x]; x++) {
01142       if (x > 0)
01143          s[ofs++] = ' ';
01144       for (src = w[x]; *src && ofs < len; src++)
01145          s[ofs++] = *src;
01146    }
01147    if (ofs == len)
01148       ofs--;
01149    s[ofs] = '\0';
01150 }

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(), __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_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_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_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_app2(), ast_pbx_outgoing_exten2(), 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(), 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(), chanspychan_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(), 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(), 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_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_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(), 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_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_cfg_update_ptp(), misdn_check_l2l1(), misdn_facility_exec(), 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_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(), 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(), 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(), 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_devicestate(), 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 1008 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(), 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().

01009 {
01010    if (ast_strlen_zero(s))
01011       return 0;
01012 
01013    /* Determine if this is a true value */
01014    if (!strcasecmp(s, "yes") ||
01015        !strcasecmp(s, "true") ||
01016        !strcasecmp(s, "y") ||
01017        !strcasecmp(s, "t") ||
01018        !strcasecmp(s, "1") ||
01019        !strcasecmp(s, "on"))
01020       return -1;
01021 
01022    return 0;
01023 }

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

Referenced by sip_notify().

00961 {
00962    char *e;
00963    char *work = s;
00964 
00965    while ((e = strchr(work, ';'))) {
00966       if ((e > work) && (*(e-1) == '\\')) {
00967          memmove(e - 1, e, strlen(e) + 1);
00968          work = e;
00969       } else {
00970          work = e + 1;
00971       }
00972    }
00973 
00974    return s;
00975 }


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 Sat Apr 12 07:12:56 2008 for Asterisk - the Open Source PBX by  doxygen 1.5.5