Mon Mar 19 11:30:55 2012

Asterisk developer's documentation


srv.h File Reference

Support for DNS SRV records, used in to locate SIP services. More...

Go to the source code of this file.

Functions

int ast_get_srv (struct ast_channel *chan, char *host, int hostlen, int *port, const char *service)
void ast_srv_cleanup (struct srv_context **context)
 Cleanup resources associated with ast_srv_lookup.
int ast_srv_get_nth_record (struct srv_context *context, int record_num, const char **host, unsigned short *port, unsigned short *priority, unsigned short *weight)
 Retrieve details from a specific SRV record.
unsigned int ast_srv_get_record_count (struct srv_context *context)
 Get the number of records for a given SRV context.
int ast_srv_lookup (struct srv_context **context, const char *service, const char **host, unsigned short *port)
 Retrieve set of SRV lookups, in order.


Detailed Description

Support for DNS SRV records, used in to locate SIP services.

Note:
Note: This SRV record support will respect the priority and weight elements of the records that are returned, but there are no provisions for retrying or failover between records.

Definition in file srv.h.


Function Documentation

int ast_get_srv ( struct ast_channel chan,
char *  host,
int  hostlen,
int *  port,
const char *  service 
)

Parameters:
chan Ast channel
host host name (return value)
hostlen Length of string "host"
port Port number (return value)
service Service tag for SRV lookup (like "_sip._udp" or "_stun._udp"

Definition at line 259 of file srv.c.

References ast_autoservice_start(), ast_autoservice_stop(), ast_copy_string(), ast_free, AST_LIST_HEAD_NOLOCK_INIT_VALUE, AST_LIST_REMOVE_HEAD, ast_search_dns(), ast_verb, context, srv_entry::host, srv_entry::list, srv_entry::port, process_weights(), and srv_callback().

Referenced by ast_get_ip_or_srv(), and create_addr().

00260 {
00261    struct srv_context context = { .entries = AST_LIST_HEAD_NOLOCK_INIT_VALUE };
00262    struct srv_entry *current;
00263    int ret;
00264 
00265    if (chan && ast_autoservice_start(chan) < 0) {
00266       return -1;
00267    }
00268 
00269    ret = ast_search_dns(&context, service, C_IN, T_SRV, srv_callback);
00270 
00271    if (context.have_weights) {
00272       process_weights(&context);
00273    }
00274 
00275    if (chan) {
00276       ret |= ast_autoservice_stop(chan);
00277    }
00278 
00279    /* TODO: there could be a "." entry in the returned list of
00280       answers... if so, this requires special handling */
00281 
00282    /* the list of entries will be sorted in the proper selection order
00283       already, so we just need the first one (if any) */
00284 
00285    if ((ret > 0) && (current = AST_LIST_REMOVE_HEAD(&context.entries, list))) {
00286       ast_copy_string(host, current->host, hostlen);
00287       *port = current->port;
00288       ast_free(current);
00289       ast_verb(4, "ast_get_srv: SRV lookup for '%s' mapped to host %s, port %d\n",
00290                 service, host, *port);
00291    } else {
00292       host[0] = '\0';
00293       *port = -1;
00294    }
00295 
00296    while ((current = AST_LIST_REMOVE_HEAD(&context.entries, list))) {
00297       ast_free(current);
00298    }
00299 
00300    return ret;
00301 }

void ast_srv_cleanup ( struct srv_context **  context  ) 

Cleanup resources associated with ast_srv_lookup.

Parameters:
context Pointer passed into ast_srv_lookup

Definition at line 247 of file srv.c.

References ast_srv_lookup(), context, and srv_entry::port.

Referenced by launch_ha_netscript(), srds_destroy_cb(), and srv_datastore_setup().

00248 {
00249    const char *host;
00250    unsigned short port;
00251 
00252    if (*context) {
00253       /* We have a context to clean up. */
00254       while (!(ast_srv_lookup(context, NULL, &host, &port))) {
00255       }
00256    }
00257 }

int ast_srv_get_nth_record ( struct srv_context context,
int  record_num,
const char **  host,
unsigned short *  port,
unsigned short *  priority,
unsigned short *  weight 
)

Retrieve details from a specific SRV record.

After calling ast_srv_lookup, the srv_context will contain the data from several records. You can retrieve the data of a specific one by asking for a specific record number. The records are sorted based on priority and secondarily based on weight. See RFC 2782 for the exact sorting rules.

Parameters:
context The context returned by ast_srv_lookup
record_num The 1-indexed record number to retrieve
[out] host The host portion of the record
[out] port The port portion of the record
[out] priority The priority portion of the record
[out] weight The weight portion of the record
Return values:
-1 Failed to retrieve information. Likely due to an out of range record_num
0 Success

Definition at line 308 of file srv.c.

References AST_LIST_TRAVERSE, context, srv_entry::host, srv_entry::list, srv_entry::port, srv_entry::priority, and srv_entry::weight.

Referenced by srv_result_read().

00310 {
00311    int i = 1;
00312    int res = -1;
00313    struct srv_entry *entry;
00314 
00315    if (record_num < 1 || record_num > context->num_records) {
00316       return res;
00317    }
00318 
00319    AST_LIST_TRAVERSE(&context->entries, entry, list) {
00320       if (i == record_num) {
00321          *host = entry->host;
00322          *port = entry->port;
00323          *priority = entry->priority;
00324          *weight = entry->weight;
00325          res = 0;
00326          break;
00327       }
00328       ++i;
00329    }
00330 
00331    return res;
00332 }

unsigned int ast_srv_get_record_count ( struct srv_context context  ) 

Get the number of records for a given SRV context.

This is meant to be used after calling ast_srv_lookup, so that one may retrieve the number of records returned during a specific SRV lookup.

Parameters:
context The context returned by ast_srv_lookup
Returns:
Number of records in context

Definition at line 303 of file srv.c.

References context.

Referenced by srv_result_read().

00304 {
00305    return context->num_records;
00306 }

int ast_srv_lookup ( struct srv_context **  context,
const char *  service,
const char **  host,
unsigned short *  port 
)

Retrieve set of SRV lookups, in order.

Parameters:
[in] context A pointer in which to hold the result
[in] service The service name to look up
[out] host Result host
[out] port Associated TCP portnum
Return values:
-1 Query failed
0 Result exists in host and port
1 No more results

Definition at line 202 of file srv.c.

References ast_calloc, ast_free, AST_LIST_FIRST, AST_LIST_HEAD_INIT_NOLOCK, AST_LIST_NEXT, AST_LIST_REMOVE_HEAD, AST_LIST_TRAVERSE, ast_search_dns(), context, srv_entry::list, process_weights(), and srv_callback().

Referenced by ast_srv_cleanup(), launch_ha_netscript(), and srv_datastore_setup().

00203 {
00204    struct srv_entry *cur;
00205 
00206    if (*context == NULL) {
00207       if (!(*context = ast_calloc(1, sizeof(struct srv_context)))) {
00208          return -1;
00209       }
00210       AST_LIST_HEAD_INIT_NOLOCK(&(*context)->entries);
00211 
00212       if ((ast_search_dns(*context, service, C_IN, T_SRV, srv_callback)) < 0) {
00213          ast_free(*context);
00214          *context = NULL;
00215          return -1;
00216       }
00217 
00218       if ((*context)->have_weights) {
00219          process_weights(*context);
00220       }
00221 
00222       (*context)->prev = AST_LIST_FIRST(&(*context)->entries);
00223       *host = (*context)->prev->host;
00224       *port = (*context)->prev->port;
00225       AST_LIST_TRAVERSE(&(*context)->entries, cur, list) {
00226          ++((*context)->num_records);
00227       }
00228       return 0;
00229    }
00230 
00231    if (((*context)->prev = AST_LIST_NEXT((*context)->prev, list))) {
00232       /* Retrieve next item in result */
00233       *host = (*context)->prev->host;
00234       *port = (*context)->prev->port;
00235       return 0;
00236    } else {
00237       /* No more results */
00238       while ((cur = AST_LIST_REMOVE_HEAD(&(*context)->entries, list))) {
00239          ast_free(cur);
00240       }
00241       ast_free(*context);
00242       *context = NULL;
00243       return 1;
00244    }
00245 }


Generated on Mon Mar 19 11:30:55 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7