Gateway Locator
Declaration
#include <gwloc.h>
int Query(gwloc_t *GwLoc, char *msg_input, char *best_match_filter);
int GetSize(gwloc_t *GwLoc);
void GetResult(gwloc_t *GwLoc, char **result, int
*lifetime);
void FreeGwLoc(gwloc_t *GwLoc);
Description
Query from SLP server the available servers for a certain service, or the attribute for a certain service, or the available service in the SLP server, or the gateway for certain phone number. The input is a pointer to char type, and the output is a pointer to an array of char with the array size returned by
GetSize(). Variable type of gwloc_t has to be declared before using these functions. To use this library,
Query() function has to be called. The argument
GwLoc from Query()
has to be passed to GetSize() to get the array size of the result of the query. Then, two allocation memories have to be defined for result and lifetime returned by
GetResult() function. If the GwLoc data type is no longer being used, it can be freed by using
FreeGwLoc() function. Failure to follow this order may result to error.
Parameters
| GwLoc | Gateway Locator internal data structure. This structure is used to hold a user query information and to make the function re-entrant. |
| msg_input | It can be slp url or phone number. An input query to find the available servers for a certain service, or the attribute for a certain service, or the available service in the SLP server, or the gateway for certain phone number. The format for the slp url is as indicated in draft-zhao-slp-url-00.txt. The format for the phone number is "country_code"-"area_code"-"local_phone_number". Example for phone number in New York, USA: 1-212-3423456. |
| best_match_filter | This parameter can be NULL. If not NULL, the output will be filtered according this matching. No error returned for inputting bad filter. Unrecognized filter will just be ignored. This filter follows the following rule: best_match_filter = attr "=" value / attr "=" value "," best_match_filter attr = attr-tag from section 5 of RFC 2608 value = "l" / "L" value = "h" / "H" value = 1*DIGIT value = "l" / "L" is to query the lowest value, value = "h" / "H" is to query the highest value, and value = 1*DIGIT is to query the value with the most closed distance to the reference value. If multiple filter combination is requested, the priority for selection criteria is from left to right. Example: best_match_filter = iptel-gw-cost-list=h,total-capacity=l,remaining-capacity=300 In this example, iptel-gw-cost-list will have a higher priority than total-capacity and remaining-capacity, and total-capacity will have a higher priority than remaining-capacity. |
| result | A one dimension array as the result of the query. This array has to have elements greater than or equal the size returned by GetSize(). |
| lifetime | If the query is not Server Request or Gateway for Internet Telephony Request, the value returned will be NULL. |
Return
Return values returned by Query() function are the return values returned by OpenSLP library.
Some of selected return values will be listed here. In addition for that, there is a return value that is returned for specific error of this Gateway Locator API.
OpenSLP Return Values
| SLP_LAST_CALL | 1 |
| SLP_OK | 0 |
| SLP_LANGUAGE_NOT_SUPPORTED | -1 |
| SLP_PARSE_ERROR | -2 |
| SLP_SCOPE_NOT_SUPPORTED | -4 |
| SLP_NOT_IMPLEMENTED | -17 |
| SLP_BUFFER_OVERFLOW | -18 |
| SLP_NETWORK_TIMED_OUT | -19 |
| SLP_PARAMETER_BAD | -22 |
| SLP_NETWORK_ERROR | -23 |
| SLP_TYPE_ERROR | -26 |
Gateway Locator Return Values
| GWLOC_BAD_QUERY | -27 | If the query inputted does not satisfy with SLP URL or Phone number standard explained in the previous section. |
Return value of GetSize() is an array size as a result of
Query(). If Query() fails or no result returned, the return value of
GetSize() is 0. If GetSize() being called without calling
Query() first, -1 will be returned.
Example Code
#include <iostream.h>
#include <stdio.h>
#include <string.h>
#include "gwloc.h"
int main(int argc, char *argv[])
{
int i;
char msg[] = "slp:///SrvRqst??type=iptel-gw;pred=(iptel-gw-prefix-list%3d1212)";
char filter[]= "iptel-gw-cost-list=h,c=l";
gwloc_t *GwLoc;
char **result;
int *lifetime;
int size, err;
GwLoc = (gwloc_t *) malloc(sizeof(gwloc_t));
err = Query(GwLoc, msg, filter);
size = GetSize(GwLoc);
// Allocate memories for result and lifetime
// as big as size.
result = (char **) malloc(sizeof(char *) * size);
lifetime = (int *) malloc(sizeof(int) * size);
GetResult(GwLoc, result, lifetime);
printf("OUTPUT:\n");
for (i = 0; i < size; i++) {
printf("%s\n", result[i]);
}
FreeGwLoc(GwLoc);
} /* main() */