RULI Synchronous SRV API

RULI's synchronous API is a simple layer built on top of the asynchronous interface in order to emulate blocking behavior.

To make a synchronous query, the application just calls a function passing the proper arguments. When the function returns, the query is complete.

The synchronous interface is suitable for multi-threaded applications.

• Main Entry Points
• Auxiliary Functions
• Types
• Functions
• Sample Program

Main Entry Points

Auxiliary Functions

Types

/* Opaque query context */
typedef struct {
  /* 
   * Only private members
   */
} ruli_sync_t;

Functions

Submit a synchronous query for the service txt_service under the domain txt_domain. If the query submission fails, a null pointer is returned. A pointer to a ruli_sync_t structure is returned when the query completes.

Input parameters

• const char *txt_service
This corresponds to the _service._protocol part of the desired SRV records. This parameter must point to a plain text, null-terminated string.
• const char *txt_domain
This corresponds to the name part of the desired SRV records. This parameter must point to a plain text, null-terminated string.
• int fallback_port
If no SRV record is found for the specified service/domain pair, the library falls back to an usual "IN A" query performed on the domain. In this case, the user-provided fallback_port is issued back as the target port of the "SRV records". This parameters allows an uniform behavior for the API. Notice one can use this parameter to "detect" when the library has resorted to an address query.

Example

ruli_sync_t *query;

query = ruli_sync_query("_smtp._tcp", "gnu.org", -1);

Release the resources allocated by ruli_sync_query() under the ruli_sync_t structure. Call ruli_sync_delete() when the answer is no longer needed.

This functions returns the answer code of the underlying SRV query. This code indicates whether the query was actually successful (RULI_SRV_CODE_OK).

If the underlying SRV query completed sucessfully (ruli_sync_srv_code() returned RULI_SRV_CODE_OK), ruli_sync_rcode() can be used to retrieve the RCODE sent by the name server.

This functions provides the list of SRV records when both SRV answer code and server RCODE are successful.

Note the SRV records provided in this list are already properly sorted for prompt usage. The whole RFC2782 priority/weight logic is already applied. The application only needs to scan the SRV records and try to use each address in the order they appear.

Sample Program

The tools/syncsolver utility provides an example of usage for the synchronous API.

$ echo _smtp._tcp.vanrein.org | ./syncsolver
_smtp._tcp.vanrein.org target=phantom.vanrein.org. port=25 addresses=:217.120.133.159
_smtp._tcp.vanrein.org target=sitemail.everyone.net. port=25 addresses=:216.200.145.35