We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
NetIC Library API Specification (PRELIMINARY) - FIWARE Forge Wiki

NetIC Library API Specification (PRELIMINARY)

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the NetIC_library API

Legal Notice

Please check the following Legal Notice to understand the rights to use these specifications.

NetIC_library API Core

Status of the API Description

This API description is a preliminary version and may change without any notice. Further, the functions described here may not be available in further software implementations.

Background

The NetIC_library API is well-suited when accessing more coarse-grained network information about a network, e.g. nodes in a network, address ranges associated with nodes or communication costs between nodes. Following this focus, the API is primarily intended for (but not limited to) use with the Topology Information Module in NetIC GE.

The API is designed as function library to support the specific needs of the underlying information retrieval: When implementing the Topology Information Module, it might have to be evaluated first from which source the requested information should be retrieved best, the selected source might even redirect the request again. As the available information might be well-suited for the needs of a wide range of applications, a single installation of a Generic Enabler might easily create a bottleneck, even if the requested information is retrieved in the end from a wide variety of sources. This bottleneck can easily be avoided if each interested application integrates the appropriate function calls which in turn flexibly can get their information from the appropriate information sources.

Introduction and Preliminaries

The NetIC_library API comprises a set of function calls which allow access to preprocessed information about an underlying network and its status.

The current implementation of the NetIC_library API focuses on the support of the Altoclient Generic Enabler instantiation (GEi) implementing the Topology Information Module in NetIC GE. As this GEi uses the ALTO protocol, proper functionality of the NetIC_library API relies on the presence of an ALTO server attached to the network management of the network of interest.

Intended Audience

This specification is intended mainly for software developers. This document provides a full specification of how to use the function calls being part of the library incorporating the NetIC_library API.

In order to use this specification, the reader should firstly have a general understanding of the NetIC Generic Enabler.

API Change History

This version of the NetIC_library API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
April 29, 2013

Initial version

How to Read This Document

It is assumed that the reader is familiar with the C programming and has basic knowledge of the ALTO protocol and IP networking.

Additional Resources

You can download the most current version of this document here. For more details about the Topology Information Module as part of the Network Information and Control (NetIC) Generic Enabler can be found here.

It is the intention of the NetIC_library API to hide most of the functionality of the network data retrieval and processing from the calling application. Nevertheless, specifications and other informative documents about ALTO can be found here.

General NetIC_library API Information

ALTO Client Handle

All API Functions require an alto client handle struct alto_alto. This allows an initialization of several ALTO clients in an application program.

ALTO Client Initialization and Close Functions

Before using the NetIC_library API, it has to be initialized. Correspondingly, a 'close' functionality is provided to release allocated resources.

It is not allowed to send any other function call than 'initialization' to the NetIC_library API before an 'initialization' function call has been finished successfully.

Correspondingly, it is not allowed to send any other function call than 'initialization' to the NetIC_library API after a 'close' function call has been finished successfully.

  • Initialization: During this process the URL of the given ALTO server is checked, a connection is set-up to the ALTO server and the ALTO service directory is retrieved. The service directory is checked for services suitable to support the calculation of network connection costs.
  • Close: All resources allocated during the initialization process are released.

Currently, the NetIC_library API supports the following functionalities:


int alto_init (struct alto_alto *handle, alto_error_t *er)
Initialization function for the ALTO client

int alto_setopt(struct alto_alto *handle, ALTOoption option, parameter)
Set the options of the ALTO client

int alto_serv_serv(struct alto_serv *handle, alto_error_t *er)
Initialize an ALTO service. *handle must point to a heap variable, otherwise alto_close will fail
when deallocting the service. int alto_serv_setopt(struct alto_service *handle, ALTOoption option, parameter) Set options for the ALTO service int alto_serv_add(struct alto_alto *ahandle, struct alto_service *shandle, alto_error_t *er) Add the ALTO service to the ALTO client. int alto_serv_rm(struct alto_alto *ahandle, struct alto_service *shandle, alto_error_t *er) Removes the ALTO service from the ALTO client and closes the service. int alto_init_easy (struct alto_alto *handle, char *server, alto_error_t *er) Easy initialization, if only one ALTO service is demanded and except for
the URI all other options can have the default values.
server is a valid URI of an ALTO directory. int alto_close (struct alto_alto *handle, alto_error_t *er) Closes the ALTO client and all added ALTO services.

Library API Options

The library API options are categorized in two groups. The ALTO client options, which affect the client shell, and the ALTO service options, which affect each service used in the ALTO client separately. All options start with “ALTOOPT_” to avoid any conflicts during compilation. In the following tables, this prefix is omitted for simplicity.

ALTO Client Options

ALTO client options are specified with the function

int alto_setopt(alto_alto *handle, ALTOoption option, <parameter>)

The type of parameter depends on option. All available options are listed below. These options are attributed to the whole ALTO client.

Option Description Type Valid Range Default
DEBUG_MODE Debug mode to provide additional information on the consol and in the Debug File int {0,1} 0
DEBUG_LOG_FILE File pointer of a file for debug information FILE* NULL and any valid FILE pointer NULL (means no debug information is written to DEBUG_LOG_FILE. If DEBUG_MODE==1, the additional debug information is sent to stdout)
NUM_SERVICES Maximum number of ALTO Services which can be initialized. size_t >0 2

ALTO Service Options

These options are attributed to every ALTO service registered in the client. ALTO service options are specified with the function

int alto_serv_setopt(alto_service *handle, ALTOoption option, <parameter>)

The type of parameter depends on option. All available options are listed below.

Option Description Type Valid Range Default
URL URL of the ALTO directory char* valid URL Required Parameter, must be set
HTTP_TIME_OUT HTTP time out in seconds long >0 5
VERBOSE_MODE Verbose mode int {0,1} 0
HTTP_BUF_SIZE Size of the buffer containing the results of the http post and get requests in Bytes size_t >0 10000
PROXY Proxy for the ALTO communication (for details see below) char* NULL or Proxy URL NULL (system settings are applied)
HTTP_REDIRECT Number of HTTP redirects followed to obtain information (Zero means that no redirects are followed) long -1 (no limit), >=0 10

Use of Proxies

The use of proxies is controlled with the ALTOOPT_PROXY option. The default is a char* pointed to NULL, which means that the system settings are applied. So the environment variable http_proxy is used, if it is set. Otherwise the option must be a char* to a zero terminated string holding the dotted IP address or the host name. Append :[port] to specify the port number other than 8080 which is the default. Any protocol specification as http:// will be ignored. If the proxy requires user and password, start the option like user:password@proxy.com. Specifying "" disables the proxy and the environment variable http_proxy is ignored.

Functions for Address Evaluation

The NetIC_library API hides most of the functionality of the network data retrieval and processing from the calling application. By this, the information which is required to be provided by the calling application to the library functions is limited to its absolute minimum. So, only source address and the destination addresses must be provided. It should be noted that if one or more of the involved servers are located in a private network (with private IP addresses) and the ALTO server is in the public IP network, the related public IP address(es) of the related intermediate NAT server(s) must be given to ensure proper results.

Currently, the NetIC_library API supports the following functionalities:

  • Get best source: For a given set of source IP addresses and a given destination IP address (usually, this would be the IP address of the server the calling application is running on), the best suited address out of the given set of source IP addresses is evaluated and returned to the calling application.
  • Get best sink: For a given set of destination IP addresses and a given source IP address (usually, this would be the IP address of the server the calling application is running on), the best suited address out of the given set of destination IP addresses is evaluated and returned to the calling application.
struct sockaddr *  alto_getbestsource(alto_alto* handle, struct sockaddr* source_addr_set, size_t num_source_adds,
                                    struct sockaddr ref_addr, alto_err* er);

Returns the best source node to refer to. The structure sockaddr is defined in /sys/socket.h
and may contain an IPv4 or an IPv6 address. Port information is ignored. 
source_addr_set is a vector of length num_source_adds containing the set of source
addresses to choose from. ref_addr names the address of the reference node. The return value points
to one of source_addr_set elements.


struct sockaddr* alto_getbestsink(alto_alto* handle, struct sockaddr* dest_sink_set, size_t num_sink_adds,
                                    struct sockaddr ref_addr, alto_err* er);

Returns the best destination node to refer to. The structure sockaddr is defined in /sys/socket.h
and may contain an IPv4 or an IPv6 address. Port information is ignored. 
dest_sink_set is a vector of length num_sink_adds containing the set of destination
addresses to choose from. ref_addr names the address of the reference node. The return value points
to one of dest_sink_set elements.

Error and Status Reporting

Error Concept

During the execution of a library function several errors or status reports may be generated. The alto client attempts to perform the requested function, even if multiple errors occur. Then it relies on the remaining correct information. This happens for example if the node selection depends on several ALTO services and one of them fails. As there are still other services to obtain information from, the overall function does not fail, however the error object contains information about the malfunctioning ALTO service. All API functions return either an int or a pointer. In case of an error, a non-zero value or a NULL pointer is returned. In addition, most functions accept an alto_err object, which contains error and status information. Instead of an alto_err object also a NULL pointer may be passed to the API function. Then no additional error information is generated.

We have to differentiate between:

  • Hierarchical errors deal with the fact that a failing subordinate function generates an error in the calling function. The error object returned by an API function then contains a function error object which references to a lower level error object from the called function. In this way it is possible that the error history can be evaluated.
  • Parallel errors occur when a function receives multiple errors during its execution. As an example, the ALTO server's answer on an endpoint cost service request is partially not readable. Then parallel errors will be given.

This concept provides the user with all information about the errors. The errors can be printed on a string using the alto_err_print function.

Error Classification

During operation of a library function, errors may occur. They can be categorized in four classes:

  • Application errors: The calling application provides wrong information, as a non-valid ALTO server URL or an invalid server IP address.
  • ALTO protocol errors: The ALTO server may respond to a request with non-readable answers or annotates services in the service directory which cannot be invoked.
  • HTTP Errors: A HTTP connection (which is used to carry the ALTO protocol) cannot be established or times out.
  • General processing errors: This class summarizes other errors, like e.g. memory allocation failures due to a lack of sufficient resources of the computer the application is running on.

To report the error to the calling application, all API functions return an error structure element.

Application of the alto_err Object

The use of the error objects follows the following scheme:

alto_err  er;
alto_err_err(&er);
 
//Call function which uses the error object
//Do something with the error object, for example print on a string:
alto_err_print (&er, s, s_size);
 
alto_err_close(&er);

The following functions support the error handling:

void alto_err_err (alto_err *er)

Constructor for empty but valid error object.
This function must be called prior to any use.

void alto_err_close (alto_err *er)

Destructor for the alto_err object. The destructor must be called
even if the tested function indicates no error by its return value.

char *alto_err_print (alto_err *er, char *s, size_t s_size)

Prints the error object on a string. s is the string and
s_size is the maximum length of the string used.
Personal tools
Create a book