F.1.6. rascal_connect_service
Prev F.1. Generic functions Next

F.1.6. rascal_connect_service

rrid_t rascal_connect_service(
	const char *name,
	const char *proto,
	const char *domain,
	dispatcher,
	void *context OPTIONAL,
	filter OPTIONAL
);

This function attempts to connect to a service trying all available servers. Behaves similar to rascal_connect. For more information read about service discovery.

service, domain

Service description. The name of the service, pointed by the name parameter, is the application level protocol, such as http, ftp, smtp or other defined by IANA or by common sense. The value of domain is the domain name to look for the service in.

For details about service resolution refer to RFC2782.

proto

The type of the transport protocol to establish the connection over. Currently, only "tcp" and "udp" are supported by connection oriented functions.

Note: the library does not take responsibility for the reliability of the communication process if the connection is made over udp; data may be lost without any notification.

dispatcher

The address of an event dispatcher function.

filter

The address of a function that filters the list of servers that provide the requested service. If this parameter is NULL, all service providers are used.

bool __rascall filter(
	void *context,
	const char *host,
	const sock_t *addr
);

The function must return true to allow the connection attempt to this server or false to skip it.

context

The value passed to rascal_connect_service, unaltered by the library.

host, addr

Host name and numeric address of the server that the library will attemp to connect to, if the filter returns true.

The library may behave in two ways. Firstly, it may call the filter function right before it is about to connect to the next server in the list, typically after it failed to reach the previous server in the list. Or, it can first call the filter for each listed server to remove unwanted servers, and then start connecting. The application should not depend on each particular behaviour, because it may change.

Return value. 

If the connection was successfully scheduled (see rascal_isok), the return value can be used to interact with the connection, such as by writing data to or reading from it. The connection can also be closed at any time by calling the rascal_cancel.

When the function fails, a corresponding error message can be retreived using the rascal_get_errmsg function.

Sample use. 

rascal_connect_service("http", "tcp", "faerion.oss",
	NULL, my_dispatcher, NULL);
Prev Up Next
F.1.5. rascal_connect Home F.1.7. rascal_dispatcher