diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/api/0.0/bc_s.png b/api/0.0/bc_s.png new file mode 100644 index 0000000..224b29a Binary files /dev/null and b/api/0.0/bc_s.png differ diff --git a/api/0.0/bc_sd.png b/api/0.0/bc_sd.png new file mode 100644 index 0000000..31ca888 Binary files /dev/null and b/api/0.0/bc_sd.png differ diff --git a/api/0.0/closed.png b/api/0.0/closed.png new file mode 100644 index 0000000..98cc2c9 Binary files /dev/null and b/api/0.0/closed.png differ diff --git a/api/0.0/dir_d44c64559bbebec7f509842c48db8b23.html b/api/0.0/dir_d44c64559bbebec7f509842c48db8b23.html new file mode 100644 index 0000000..c93d3ed --- /dev/null +++ b/api/0.0/dir_d44c64559bbebec7f509842c48db8b23.html @@ -0,0 +1,103 @@ + + +
+ + + + +
+ libpaf 1.0.1
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.0.1
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For simplicity, the library implementing this API is refered to as libpaf
, although there might be other implementations as well.
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with a string value.
+In case the transport protocol uses TLS, three optional keys may be presented in the server object:
+In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
A service publish via the library has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, beforing the paf_publish() call. The TTL must be an non-negative integer.
libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.0.1
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes has been commited in the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not event be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context.
+It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.1.11
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For a description of the Pathfinder data model, refer to the Pathfinder Protocol Specification. Note: there are important semantical differences between certain operations on the protocol level, compared to this API (e.g., paf_publish() doesn't have the exact same semantics as the publish
protocol-level command).
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with the server's address in XCM format as its value.
+A server object may have a key "localAddress", in which case this XCM-formatted address will be bound to before establishing an outgoing connection.
+A server object may have a key "minProtocolVersion", used to increase the minimum protocol version advertised as supported by libpaf
to that server. If "minProtocolVersion" is set higher than the maximum version suported by libpaf
(i.e., > 3), no connections will be initiated to that server.
A server object may have the key "maxProtocolVersion", used to decrease the maximum protocol version advertised by libpaf
. If the "maxProtocolVersion" is set lower than the minimum version supported by libpaf
(i.e., < 2), no connections will be initiated to that server.
If both "minProtocolVersion" and "maxProtocolVersion" are set, "minProtocolVersion" must be equal to or lower than "maxProtocolVersion".
+A server object may have a keys "minIdleTime" or "maxIdleTime" to configure client-side Liveness Tracking, and override the PAF_IDLE_MIN
and PAF_IDLE_MAX
values and the compile-time defaults (in case the environment variables are not set).
If both "minIdleTime" and "maxIdleTime" are set, "minIdleTime" must be equal to or lower than "maxIdleTime".
+A server object may include a key "networkNamespace". If present, the library will make sure the outoing transport layer connection originates from a Linux network namespace named per the key's value. To switch between network namespaces, the process needs the CAP_SYS_ADMIN
capability. The network namespace needs to be named as per iproute2 conventions.
In case the transport protocol uses TLS, a number of optional keys may be present in the server object:
+Setting tlsCrlFile will enable certificate revocation verification, and requires libpaf
to be linked to libxcm
version v1.9.0 or later.
In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the network namespace and the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
On connections where the Pathfinder protocol version 3 is negotiated to be used, libpaf
performs server liveness tracking on the level of the Pathfinder protocol.
On v3 connections, libpaf
imposes an upper limit on how long time the remote peer is allowed to remain idle. When maximum idle time is approaching, libpaf will query the server to ensure it is still alive. In case the server also employs liveness checking, any server queries will be treated as a sign of life, and make libpaf post-poned any liveness query.
The maximum idle time is 30 seconds by default, and may be overriden by setting the PAF_IDLE_MAX
environment variable.
The actual max idle time used may be lower than PAF_IDLE_MAX
, in case low-TTL services have been published by the application, or have been matched in one of its subscriptions.
The actual max idle time will never be set to lower than PAF_IDLE_MIN
, which is 4 seconds by default. To protect the server, libpaf
will treat PAF_IDLE_MIN
set lower than 1 second as set to 1 second.
On version 2 connections, libpaf depends on the transport protocol (e.g., TCP) for liveness checking.
+On version 3 connections, TCP keepalive is disabled.
+The minimum idle time is also used as an upper bound for the total amount of time the initial transport connection establishment (e.g., TCP three-way handshake and TLS hello) and the Pathfinder protocol-level hello transaction is allowed to take.
+The host part of the XCM server address in the Domain Configuration may either be a DNS hostname or an IP address in string format. If a Pathfinder server DNS hostname resolves to multiple A or AAAA records, libpaf
will interpret that as a single, multihomed, server.
In such a scenario, libpaf
will attempt to establish a TCP connection the server via all available IP addresses, but will employ only at most one connection for the actual Pathfinder protocol signaling. The Happy Eyeballs (RFC 6555) method is used.
Multihomed servers are only supported when libpaf
is running linked to XCM v1.9.0 (or later). For older XCM versions, only the first (i.e., most preferred) IP address will be considered.
A service published using libpaf
has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, before the paf_publish() call.
The paf_set_ttl() function may be used to update the TTL for a specific service.
+For a description of how service TTLs work in Pathfinder, please refer to the Pathfinder protocol specification.
+libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.1.11
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_set_ttl (struct paf_context *context, int64_t service_id, int64_t ttl) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+A context may not be left unattended. See paf_process() for details how to avoid such a situation.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server. Actual publication may be deferred until the next, or some future, paf_process() call.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes have been commited to the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_set_ttl | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | int64_t | +ttl | +
+ | ) | ++ |
Change service TTL.
+This function modifies an already-published service's time to live (TTL) setting.
+The successful return of this function means the change has been committed in the supplied context. It may or may not have propagated further (i.e to the server or to any other client).
+Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | ttl | A non-negative integer specifying the new TTL (in s). |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not even be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context
.
It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.1.12
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For a description of the Pathfinder data model, refer to the Pathfinder Protocol Specification. Note: there are important semantical differences between certain operations on the protocol level, compared to this API (e.g., paf_publish() doesn't have the exact same semantics as the publish
protocol-level command).
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with the server's address in XCM format as its value.
+A server object may have a key "localAddress", in which case this XCM-formatted address will be bound to before establishing an outgoing connection.
+A server object may have a key "minProtocolVersion", used to increase the minimum protocol version advertised as supported by libpaf
to that server. If "minProtocolVersion" is set higher than the maximum version suported by libpaf
(i.e., > 3), no connections will be initiated to that server.
A server object may have the key "maxProtocolVersion", used to decrease the maximum protocol version advertised by libpaf
. If the "maxProtocolVersion" is set lower than the minimum version supported by libpaf
(i.e., < 2), no connections will be initiated to that server.
If both "minProtocolVersion" and "maxProtocolVersion" are set, "minProtocolVersion" must be equal to or lower than "maxProtocolVersion".
+A server object may have a keys "minIdleTime" or "maxIdleTime" to configure client-side Liveness Tracking, and override the PAF_IDLE_MIN
and PAF_IDLE_MAX
values and the compile-time defaults (in case the environment variables are not set).
If both "minIdleTime" and "maxIdleTime" are set, "minIdleTime" must be equal to or lower than "maxIdleTime".
+A server object may include a key "networkNamespace". If present, the library will make sure the outoing transport layer connection originates from a Linux network namespace named per the key's value. To switch between network namespaces, the process needs the CAP_SYS_ADMIN
capability. The network namespace needs to be named as per iproute2 conventions.
In case the transport protocol uses TLS, a number of optional keys may be present in the server object:
+Setting tlsCrlFile will enable certificate revocation verification, and requires libpaf
to be linked to libxcm
version v1.9.0 or later.
In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the network namespace and the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
On connections where the Pathfinder protocol version 3 is negotiated to be used, libpaf
performs server liveness tracking on the level of the Pathfinder protocol.
On v3 connections, libpaf
imposes an upper limit on how long time the remote peer is allowed to remain idle. When maximum idle time is approaching, libpaf will query the server to ensure it is still alive. In case the server also employs liveness checking, any server queries will be treated as a sign of life, and make libpaf post-poned any liveness query.
The maximum idle time is 30 seconds by default, and may be overriden by setting the PAF_IDLE_MAX
environment variable.
The actual max idle time used may be lower than PAF_IDLE_MAX
, in case low-TTL services have been published by the application, or have been matched in one of its subscriptions.
The actual max idle time will never be set to lower than PAF_IDLE_MIN
, which is 4 seconds by default. To protect the server, libpaf
will treat PAF_IDLE_MIN
set lower than 1 second as set to 1 second.
On version 2 connections, libpaf depends on the transport protocol (e.g., TCP) for liveness checking.
+On version 3 connections, TCP keepalive is disabled.
+The minimum idle time is also used as an upper bound for the total amount of time the initial transport connection establishment (e.g., TCP three-way handshake and TLS hello) and the Pathfinder protocol-level hello transaction is allowed to take.
+The host part of the XCM server address in the Domain Configuration may either be a DNS hostname or an IP address in string format. If a Pathfinder server DNS hostname resolves to multiple A or AAAA records, libpaf
will interpret that as a single, multihomed, server.
In such a scenario, libpaf
will attempt to establish a TCP connection the server via all available IP addresses, but will employ only at most one connection for the actual Pathfinder protocol signaling. The Happy Eyeballs (RFC 6555) method is used.
Multihomed servers are only supported when libpaf
is running linked to XCM v1.9.0 (or later). For older XCM versions, only the first (i.e., most preferred) IP address will be considered.
A service published using libpaf
has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, before the paf_publish() call.
The paf_set_ttl() function may be used to update the TTL for a specific service.
+For a description of how service TTLs work in Pathfinder, please refer to the Pathfinder protocol specification.
+libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.1.12
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_set_ttl (struct paf_context *context, int64_t service_id, int64_t ttl) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+A context may not be left unattended. See paf_process() for details how to avoid such a situation.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server. Actual publication may be deferred until the next, or some future, paf_process() call.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes have been commited to the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_set_ttl | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | int64_t | +ttl | +
+ | ) | ++ |
Change service TTL.
+This function modifies an already-published service's time to live (TTL) setting.
+The successful return of this function means the change has been committed in the supplied context. It may or may not have propagated further (i.e to the server or to any other client).
+Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | ttl | A non-negative integer specifying the new TTL (in s). |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not even be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context
.
It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.12
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.1.12
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.1.11
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For a description of the Pathfinder data model, refer to the Pathfinder Protocol Specification. Note: there are important semantical differences between certain operations on the protocol level, compared to this API (e.g., paf_publish() doesn't have the exact same semantics as the publish
protocol-level command).
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with the server's address in XCM format as its value.
+A server object may have a key "localAddress", in which case this XCM-formatted address will be bound to before establishing an outgoing connection.
+A server object may have a key "minProtocolVersion", used to increase the minimum protocol version advertised as supported by libpaf
to that server. If "minProtocolVersion" is set higher than the maximum version suported by libpaf
(i.e., > 3), no connections will be initiated to that server.
A server object may have the key "maxProtocolVersion", used to decrease the maximum protocol version advertised by libpaf
. If the "maxProtocolVersion" is set lower than the minimum version supported by libpaf
(i.e., < 2), no connections will be initiated to that server.
If both "minProtocolVersion" and "maxProtocolVersion" are set, "minProtocolVersion" must be equal to or lower than "maxProtocolVersion".
+A server object may have a keys "minIdleTime" or "maxIdleTime" to configure client-side Liveness Tracking, and override the PAF_IDLE_MIN
and PAF_IDLE_MAX
values and the compile-time defaults (in case the environment variables are not set).
If both "minIdleTime" and "maxIdleTime" are set, "minIdleTime" must be equal to or lower than "maxIdleTime".
+A server object may include a key "networkNamespace". If present, the library will make sure the outoing transport layer connection originates from a Linux network namespace named per the key's value. To switch between network namespaces, the process needs the CAP_SYS_ADMIN
capability. The network namespace needs to be named as per iproute2 conventions.
In case the transport protocol uses TLS, a number of optional keys may be present in the server object:
+Setting tlsCrlFile will enable certificate revocation verification, and requires libpaf
to be linked to libxcm
version v1.9.0 or later.
In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the network namespace and the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
On connections where the Pathfinder protocol version 3 is negotiated to be used, libpaf
performs server liveness tracking on the level of the Pathfinder protocol.
On v3 connections, libpaf
imposes an upper limit on how long time the remote peer is allowed to remain idle. When maximum idle time is approaching, libpaf will query the server to ensure it is still alive. In case the server also employs liveness checking, any server queries will be treated as a sign of life, and make libpaf post-poned any liveness query.
The maximum idle time is 30 seconds by default, and may be overriden by setting the PAF_IDLE_MAX
environment variable.
The actual max idle time used may be lower than PAF_IDLE_MAX
, in case low-TTL services have been published by the application, or have been matched in one of its subscriptions.
The actual max idle time will never be set to lower than PAF_IDLE_MIN
, which is 4 seconds by default. To protect the server, libpaf
will treat PAF_IDLE_MIN
set lower than 1 second as set to 1 second.
On version 2 connections, libpaf depends on the transport protocol (e.g., TCP) for liveness checking.
+On version 3 connections, TCP keepalive is disabled.
+The minimum idle time is also used as an upper bound for the total amount of time the initial transport connection establishment (e.g., TCP three-way handshake and TLS hello) and the Pathfinder protocol-level hello transaction is allowed to take.
+The host part of the XCM server address in the Domain Configuration may either be a DNS hostname or an IP address in string format. If a Pathfinder server DNS hostname resolves to multiple A or AAAA records, libpaf
will interpret that as a single, multihomed, server.
In such a scenario, libpaf
will attempt to establish a TCP connection the server via all available IP addresses, but will employ only at most one connection for the actual Pathfinder protocol signaling. The Happy Eyeballs (RFC 6555) method is used.
Multihomed servers are only supported when libpaf
is running linked to XCM v1.9.0 (or later). For older XCM versions, only the first (i.e., most preferred) IP address will be considered.
A service published using libpaf
has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, before the paf_publish() call.
The paf_set_ttl() function may be used to update the TTL for a specific service.
+For a description of how service TTLs work in Pathfinder, please refer to the Pathfinder protocol specification.
+libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.1.11
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_set_ttl (struct paf_context *context, int64_t service_id, int64_t ttl) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+A context may not be left unattended. See paf_process() for details how to avoid such a situation.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server. Actual publication may be deferred until the next, or some future, paf_process() call.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes have been commited to the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_set_ttl | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | int64_t | +ttl | +
+ | ) | ++ |
Change service TTL.
+This function modifies an already-published service's time to live (TTL) setting.
+The successful return of this function means the change has been committed in the supplied context. It may or may not have propagated further (i.e to the server or to any other client).
+Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | ttl | A non-negative integer specifying the new TTL (in s). |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not even be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context
.
It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.1.11
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.1.11
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.0.0
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+
+ libpaf 1.0.0
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes has been commited in the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not event be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context.
+It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.0
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.0.0
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.0.1
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For simplicity, the library implementing this API is referred to as libpaf
, although there might be other implementations as well.
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with a string value.
+In case the transport protocol uses TLS, three optional keys may be present in the server object:
+In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
A service publish via the library has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, beforing the paf_publish() call. The TTL must be an non-negative integer.
libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.0.1
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes has been commited in the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not event be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context.
+It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.0.1
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.0.1
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.1.0
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For simplicity, the library implementing this API is referred to as libpaf
, although there might be other implementations as well.
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with a string value.
+In case the transport protocol uses TLS, three optional keys may be present in the server object:
+In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
A service publish using libpaf
has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, before the paf_publish() call.
The paf_set_ttl() function may be used to update the TTL for a specific service.
+libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.1.0
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_set_ttl (struct paf_context *context, int64_t service_id, int64_t ttl) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes have been commited to the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_set_ttl | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | int64_t | +ttl | +
+ | ) | ++ |
Change service TTL.
+This function modifies an already-published service's time to live (TTL) setting.
+The successful return of this function means the change has been committed in the supplied context. It may or may not have propagated further (i.e to the server or to any other client).
+Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | ttl | A non-negative integer specifying the new TTL (in s). |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not even be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context.
+It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.0
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.1.0
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+Files | |
paf.h | |
Core Pathfinder Client Library API. | |
paf_err.h | |
paf_match.h | |
Pathfinder Client Library's Subscription Match-related Data Structure. | |
paf_props.h | |
Pathfinder Service Properties API. | |
paf_value.h | |
Pathfinder Property Value API. | |
+ libpaf 1.1.1
+
+ |
+
▼ include | |
paf.h | Core Pathfinder Client Library API |
paf_err.h | |
paf_match.h | Pathfinder Client Library's Subscription Match-related Data Structure |
paf_props.h | Pathfinder Service Properties API |
paf_value.h | Pathfinder Property Value API |
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
This is the documentation for the Pathfinder Client Library API.
+The Pathfinder Client Library API is used to access one or more Pathfinder service discovery domains, either as a service producer or consumer.
+All the functions in this API are non-blocking in the sense that no blocking system calls are made.
+For simplicity, the library implementing this API is referred to as libpaf
, although there might be other implementations as well.
A Pathfinder service discovery domain is a namespace shared by all Pathfinder clients attached to that domain. A service publish by one client can be seen by all other clients attached to that domain. A domain is served by one or more Pathfinder server instances.
+In order to participate in a domain, an application issues paf_attach() with the appropriate service discovery domain name. It need not know what servers are currently serving that domain.
+The mapping between a service discovery domain name and the set of addresses to the Pathfinder servers serving this domain is kept in a file. The configuration for a particular domain name must be stored in a file with the same name as the domain, and be located in the domain files directory. The compile-time default location is is /run/paf/domains
.d/.
The directory may contain an arbitrary number of domains.
+In case the domain file does not exist at the time of the paf_attach() call, libpaf
will periodically check if it has been created.
In case the file is modified (e.g., a server is added, removed or has its address changed), the file will be re-read by libpaf
. If the file is removed, the set of servers is considered empty.
The environment variable PAF_DOMAINS
may set in case a non-standard directory is preferred over the default.
libpaf
supports two file formats. Either the contents of the file is a newline-separated list of XCM addresses, or a JSON object.
The newline-separated format allows for comments. In this format, empty lines and lines beginning with '#' are ignored. JSON does not support comments.
+A domain file in the JSON format must contain a root JSON object, with a key "servers". The value of "servers" must be an array of zero or more JSON objects, each representing a server.
+The server object must have a key "address", with the server's address in XCM format as its value.
+A server object may include a key "networkNamespace". If present, the library will make sure the outoing transport layer connection originates from a Linux network namespace named per the key's value. To switch between network namespaces, the process needs the CAP_SYS_ADMIN
capability. The network namespace needs to be named as per iproute2 conventions.
In case the transport protocol uses TLS, three optional keys may be present in the server object:
+In case some/all of the certificate file related keys are left out, libpaf
will fall back to using the XCM defaults.
Below is an example of a domain file in JSON format:
The same configuration (minus the network namespace and the certificate-related configuration), but in the newline-separated format:
For all domains the application currently has attached to, libpaf
tracks domain file changes. This check is performed periodically every ~5 s. A small random component is added to avoid load spikes, in case there are many clients on the same system.
This default interval may be changed by setting the PAF_RESCAN
environment variable. The value a floating point number (in s). If set to zero, the rescanning is disabled.
In case the connection to a server is lost, or never was successfully established in the first place, libpaf
will perform another attempt at a later time.
libpaf
uses exponential back-off. The first retry is scheduled to occur after 10 ms. Every failed attempt double the retry interval, up to a maximum of 5 s. These two defaults may be changed by setting the PAF_RECONNECT_MIN
and/or PAF_RECONNECT_MAX
environment variables.
A service publish using libpaf
has a time-to-live (TTL) of 30 s. This default may be changed by setting the PAF_TTL
environment variable, before the paf_publish() call.
The paf_set_ttl() function may be used to update the TTL for a specific service.
+libpaf
comes with built-in support for tracing. The library supports writing traces to stderr in human-readable format, or direct them to LTTng. The former is always available, and the latter is available if the library is built with LTTng support.
To enable stderr-type tracing, set the PAF_DEBUG
environment variable to "1", before starting the application.
To enabled LTTng tracing, enable the relevant libpaf LTTng tracepoints.
+All API calls are multi-thread (MT) safe when called on different context (for paf.h API calls) or service properties (for paf_props.h API calls). Thus, one thread may safely call paf_publish(), while another thread calls the same (or a different) paf_*() function, but on another context.
+No API calls are MT safe when called on the same context or service properties. For that to work, external synchronization (e.g., a mutex lock) is required.
+
+ libpaf 1.1.1
+
+ |
+
Core Pathfinder Client Library API. +More...
+#include <stdint.h>
#include <sys/types.h>
#include <paf_props.h>
#include <paf_match.h>
#include <paf_err.h>
Go to the source code of this file.
++Functions | |
struct paf_context * | paf_attach (const char *domain_name) |
int64_t | paf_publish (struct paf_context *context, const struct paf_props *props) |
int | paf_modify (struct paf_context *context, int64_t service_id, const struct paf_props *props) |
void | paf_set_ttl (struct paf_context *context, int64_t service_id, int64_t ttl) |
void | paf_unpublish (struct paf_context *context, int64_t service_id) |
int64_t | paf_subscribe (struct paf_context *context, const char *filter, paf_match_cb match_cb, void *user) |
void | paf_unsubscribe (struct paf_context *context, int64_t subscription_id) |
int | paf_fd (struct paf_context *context) |
int | paf_process (struct paf_context *context) |
void | paf_detach (struct paf_context *context) |
void | paf_close (struct paf_context *context) |
char * | paf_filter_escape (const char *s) |
Core Pathfinder Client Library API.
+struct paf_context * paf_attach | +( | +const char * | +domain_name | ) | ++ |
Attach to a domain.
+This function attaches to a Pathfinder domain. The return value is a context, which is used to store library-internal service and subscription state as handed to it by the application, and subscription matches from a remote server, as well as protocol-related state for server communication.
+paf_attach() will succeed even though the domain doesn't currently exists on the local system. Any remote communication failure, to the extent any such happens during paf_attach(), also doesn't make the call fail.
+[in] | domain_name | The name of the Pathfinder domain. |
int64_t paf_publish | +( | +struct paf_context * | +context, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Publish a service.
+This function allows the application to inform the library of a service it wishes to have published at any time the context has an connection to a server, serving that domain.
+The successful return of paf_publish() indicates that the service as been accepted into the library's context. It does not mean that the service has yet been successfully published in a server, or even that there is a connection to a server.
+[in] | context | A reference to the domain where the service should be published. |
[in] | props | The properties of this service. Must be non-NULL, but may be an empty set. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties' maximum size was exceeded. |
int paf_modify | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | const struct paf_props * | +props | +
+ | ) | ++ |
Modify a service's properties.
+This function modifies an already-published service's properties.
+The successful return of this function means the changes have been commited to the supplied context, but does not mean they have propagated further (i.e to the server or to any other client, including subscriptions issued via this context).
+The properties supplied in props
will replace those currently in use by the service. Thus, all previous properties will be removed, and replaced in their entirety by those in props
.
Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | props | The properties that should replace the service current properties. |
Return Code | Description |
---|---|
PAF_ERR_PROPS_TOO_LARGE | The service properties maxiumum size was been exceeded. |
void paf_set_ttl | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id, | +
+ | + | int64_t | +ttl | +
+ | ) | ++ |
Change service TTL.
+This function modifies an already-published service's time to live (TTL) setting.
+The successful return of this function means the change has been committed in the supplied context. It may or may not have propagated further (i.e to the server or to any other client).
+Only services published using the supplied context
may be modified.
[in] | context | A reference to the service's domain. |
[in] | service_id | The id of the service as returned by paf_publish(). |
[in] | ttl | A non-negative integer specifying the new TTL (in s). |
void paf_unpublish | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +service_id | +
+ | ) | ++ |
Unpublish a service.
+This function allows the application to inform the library of a Pathfinder service it wishes to have a previously published service removed.
+In case the service is currently published in a server, it may not yet have been removed at the time of paf_unpublish() call completion. There might not even be a connection to the server (where the service may still be lingering in an orphan state).
+Only services published using the supplied context
may be unpublished.
[in] | context | A reference to the context in where the service was published. |
[in] | service_id | The id of the service as returned by paf_publish(). |
int64_t paf_subscribe | +( | +struct paf_context * | +context, | +
+ | + | const char * | +filter, | +
+ | + | paf_match_cb | +match_cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Issue a service subscription.
+This function registers a service subscription in the supplied context.
+The filter can be used to specify what services are interesting to the application.
+The filter syntax is similar to that of LDAP (see RFC 2254), but with some differences, mainly in the area of the escaping mechanism (allowing special characters in search filter name or values).
+A search filter example: (&(name=my-service)(area=51))
Supplying NULL in filter
will results in a "match all" filter.
In case of a matching service appearing, is being modified, or disappeared, the match_cb
function will be called. The callback function will only be called at the time of paf_process(). See paf_match_cb and paf_match_type for more information.
The successful return of paf_subscribe() does not guarantee that the subscription has been forwarded to a server.
+[in] | context | A reference to the domain in which the subscription should be issued. |
[in] | filter | A search filter in string format, or NULL. |
[in] | match_cb | The callback used to notify the application of a matching service. |
[in] | user | A user-supplied opaque pointer which will be supplied back to the application at every match callback call. |
Return Code | Description |
---|---|
PAF_ERR_FILTER_TOO_LARGE | The filter exceeds the maximum size. |
PAF_ERR_INVALID_FILTER_SYNTAX | Invalid filter syntax. |
void paf_unsubscribe | +( | +struct paf_context * | +context, | +
+ | + | int64_t | +subscription_id | +
+ | ) | ++ |
Unsubscribe to a service.
+This function cancels a subscription previously issued in the supplied context
.
After paf_unsubscribe() call completition, the corresponding callback will no longer be called.
+[in] | context | A reference to the context in where the subscription was issued. |
[in] | subscription_id | The id of the subscription as returned by paf_subscribe(). |
int paf_fd | +( | +struct paf_context * | +context | ) | ++ |
Query a context for it's file descriptor.
+The file descriptor returned by this function allows the context to signal when a call paf_process() is likely to allow it to make progress. Progress here means things like receiving and processing Pathfinder wire protocol messages, handling timeout, and calling user callbacks.
+The application should wait for the fd to become readable (i.e. it should be put into the readfds set for select(), or be marked POLLIN/EPOLLIN in case poll()/epoll() is used), and then call paf_process().
+The file descriptor is stable (i.e the number doesn't change) across the life-time of the context. To what underlying file description it's pointing also doesn't change (a detail relevent for its use in epoll()). The fd is also unique to this context (i.e. several context will not reuse the same fd).
+[in] | context | The context. |
int paf_process | +( | +struct paf_context * | +context | ) | ++ |
Perform processing related to a particular context.
+This function will processing related to the supplied context. Such processing can be things like establishing a connection to a server, sending messages to or receiving messages from a server or check for timeout on stale (orphan) services.
+As a part of paf_process() call, the library may invoke one or more paf_match_cb subscription callbacks. Such a callback may not call back into any paf.h core API functions with the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc).
+paf_process() may be called at any point, but will typically be called after select() (or equivalent I/O multiplexing function) has returned, and fds related to a particular context are the cause of the select() call being unblocked.
+A context may not be left unattended (i.e. no calls to paf_process()) by the application for a long duration of time, unless the context's fds aren't becoming active. In other words, the context's fd should always be in the set of fds supplied by the application to select(), until up to the point it is closed with paf_close().
+paf_process() will never fail, and the return value is only used to inform the application that the context detachment it ordered (via paf_detach()) has completed.
+[in] | context | The context. |
void paf_detach | +( | +struct paf_context * | +context | ) | ++ |
Detach the context.
+This function will initiate the process of detaching the context from any server, attempting to unpublish all services, remove all subscriptions, and finish any outstanding protocol transactions (e.g. unpublish operations that might not yet have finished).
+To allow the detaching to happen, the application should continue to use select() for wait for the context's fd to become readable, and paf_process() to allow it to make progress.
+paf_process() will return PAF_ERR_DETACHED when the process has completed (or timed out).
+Since unpublication is a best-effort exercise, in case the server does not respond within a resonable time, detaching will finish.
+After paf_detach() has been called, only paf_fd(), paf_process() and paf_close() may be called.
+[in] | context | The context. |
void paf_close | +( | +struct paf_context * | +context | ) | ++ |
Close the context.
+This function will free all resources associated with context.
+It is legal to call this function, even if the context is still attached (i.e. paf_detach() was not called, or paf_process() has not yet returned PAF_ERR_DETACHED. If it was not detached the services will not be unpublished. Upon client disconnect, such services will be considered orphans, and will be available until their time-to-live (TTL) has expired.
+[in] | context | The context. |
char * paf_filter_escape | +( | +const char * | +s | ) | ++ |
Escape special characters for strings used in filters.
+This function will copy the input string, escaping any characters which have a special meaning in the subscription filter language (see paf_subscribe()).
+The input string may contain arbitrary non-NUL characters, and may be of arbitrary length. However, there is a maximum filter size.
+Since the same escaping mechanism is used for both service property names and string values, paf_filter_escape() may be used for both types.
+The string returned is heap-allocated, and it's the caller obligation to use free() to free its memory.
+This function for creating filter expressions only. It is not needed and should not be used while creating service property string-type values (see paf_value.h) for use in paf_publish().
+[in] | s | The service property name or string value to be escaped. |
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
Pathfinder Client Library's Subscription Match-related Data Structure. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) |
+Enumerations | |
enum | paf_match_type { paf_match_type_appeared +, paf_match_type_modified +, paf_match_type_disappeared + } |
Pathfinder Client Library's Subscription Match-related Data Structure.
+typedef void(* paf_match_cb) (enum paf_match_type match_type, int64_t service_id, const struct paf_props *props, void *user) | +
Callback to notify the application of matching services.
+A subscription callback may not call back into any paf.h core API functions taking the current context as it's input (e.g. paf_subscribe(), paf_unsubscribe() etc). Such calls must be defered to after the callback has returned. Calls to other Pathfinder API functions, for example functions in paf_props.h or paf_value.h may be made.
+[in] | service_id | The service id of the matching service. |
[in] | props | The properties of the matching service. NULL for disappeared type matches. |
[in] | match_type | The type of match. |
[in] | user | An application-supplied pointer (see paf_subscribe()). |
enum paf_match_type | +
Type of subscription match.
+
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
Pathfinder Service Properties API. +More...
+ +Go to the source code of this file.
++Typedefs | |
typedef void(* | paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) |
+Functions | |
struct paf_props * | paf_props_create (void) |
void | paf_props_add (struct paf_props *props, const char *name, const struct paf_value *value) |
void | paf_props_add_int64 (struct paf_props *props, const char *name, int64_t value) |
void | paf_props_add_str (struct paf_props *props, const char *name, const char *value) |
size_t | paf_props_get (const struct paf_props *props, const char *prop_name, const struct paf_value **values, size_t capacity) |
const struct paf_value * | paf_props_get_one (const struct paf_props *props, const char *prop_name) |
void | paf_props_foreach (const struct paf_props *props, paf_props_foreach_cb cb, void *user) |
bool | paf_props_equal (const struct paf_props *props_a, const struct paf_props *props_b) |
size_t | paf_props_num_values (const struct paf_props *props) |
size_t | paf_props_num_names (const struct paf_props *props) |
struct paf_props * | paf_props_clone (const struct paf_props *orig) |
void | paf_props_destroy (struct paf_props *props) |
Pathfinder Service Properties API.
+Service properties are a multimap. Thus, each property name may be assoicated to one or more values.
+typedef void(* paf_props_foreach_cb) (const char *prop_name, const struct paf_value *prop_value, void *user) | +
Callback function prototype used for iteration.
+ +struct paf_props * paf_props_create | +( | +void | +) | ++ |
Create a service properties instance.
+void paf_props_add | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const struct paf_value * | +value | +
+ | ) | ++ |
Add a property.
+This function adds a property to props
.
Both the name
and the value
will be copied, and thus will still be owned by the caller at call completion.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_int64 | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | int64_t | +value | +
+ | ) | ++ |
Add a property with an integer value.
+This function adds a property with an integer value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
void paf_props_add_str | +( | +struct paf_props * | +props, | +
+ | + | const char * | +name, | +
+ | + | const char * | +value | +
+ | ) | ++ |
Add a property with a string value.
+This function adds a property with a string value to props
.
[in] | props | The service properties instance. |
[in] | name | The name of the property to be added. |
[in] | value | The value of the property to be added. |
size_t paf_props_get | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name, | +
+ | + | const struct paf_value ** | +values, | +
+ | + | size_t | +capacity | +
+ | ) | ++ |
Retrieve all values for a particular property.
+This function retrieves the zero-or-more values associated with the supplied prop_name
, and stores them in values
.
If values'
capacity is to small to hold pointers to all values, as many values as can fit will be stored. The actual number of values present in props
will be returned regardless.
In case capacity
is 0, props
may be left NULL. Such a call may be useful to allow pre-allocation of a suitably-sized values
array, before the actual paf_props_get() call.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose values is to be retrieved. |
[out] | values | A pointer to an user-allocated array of paf_value pointers. |
[in] | capacity | The number of elements values can hold. |
prop_name
(even in the case this number is larger than capacity
). const struct paf_value * paf_props_get_one | +( | +const struct paf_props * | +props, | +
+ | + | const char * | +prop_name | +
+ | ) | ++ |
Retrieve a value for a particular property.
+This function returns a value associated with the supplied prop_name
.
[in] | props | The service properties instance. |
[in] | prop_name | The name of the property whose value is to be retrieved. |
prop_name
, or NULL in case there is none. void paf_props_foreach | +( | +const struct paf_props * | +props, | +
+ | + | paf_props_foreach_cb | +cb, | +
+ | + | void * | +user | +
+ | ) | ++ |
Iterate over all name-value pairs.
+This function calls the supplied callback function cb
for each property name-value pair in props
.
props
may not be modified during the iteration.
[in] | props | The service properties instance. |
[in] | cb | The callback function. |
[in] | user | An opaque pointer, supplied back to the application in every cb call. |
bool paf_props_equal | +( | +const struct paf_props * | +props_a, | +
+ | + | const struct paf_props * | +props_b | +
+ | ) | ++ |
Compares two property multimaps for equality (by value).
+[in] | props_a | A service properties instance. |
[in] | props_b | A service properties instance. |
props_a
and props_b
are equal, false otherwise. size_t paf_props_num_values | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property name-value pairs.
+This function returns the total number of name-value pairs in the properties instance.
+[in] | props | The service properties instance. |
size_t paf_props_num_names | +( | +const struct paf_props * | +props | ) | ++ |
Returns the total number of property names in the properties instance.
+[in] | props | The service properties instance. |
struct paf_props * paf_props_clone | +( | +const struct paf_props * | +orig | ) | ++ |
Returns a copy of the supplied properties instance.
+[in] | orig | The service properties instance to be copied. |
void paf_props_destroy | +( | +struct paf_props * | +props | ) | ++ |
Destroys a properties instance.
+This function destroys the properties instance and frees all the resources associated with it.
+[in] | props | The service properties instance. |
+ libpaf 1.1.1
+
+ |
+
+ libpaf 1.1.1
+
+ |
+
Pathfinder Property Value API. +More...
+#include <stdbool.h>
#include <stdint.h>
Go to the source code of this file.
++Functions | |
bool | paf_value_is_int64 (const struct paf_value *value) |
bool | paf_value_is_str (const struct paf_value *value) |
struct paf_value * | paf_value_int64_create (int64_t value) |
int64_t | paf_value_int64 (const struct paf_value *value) |
struct paf_value * | paf_value_str_create (const char *value) |
const char * | paf_value_str (const struct paf_value *value) |
bool | paf_value_equal (const struct paf_value *value_a, const struct paf_value *value_b) |
struct paf_value * | paf_value_clone (const struct paf_value *orig) |
void | paf_value_destroy (struct paf_value *value) |
Pathfinder Property Value API.
+Service properties can be either integer or a string.
+bool paf_value_is_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is an integer.
+value
is an integer, or false otherwise. bool paf_value_is_str | +( | +const struct paf_value * | +value | ) | ++ |
Checks if the value is a string.
+value
is a string, or false otherwise. struct paf_value * paf_value_int64_create | +( | +int64_t | +value | ) | ++ |
Creates an integer value.
+[in] | value | The 64-bit value used to initialize value . |
int64_t paf_value_int64 | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the integer value of value
.
[in] | value | A value of type integer. |
value
. struct paf_value * paf_value_str_create | +( | +const char * | +value | ) | ++ |
Creates a string value.
+[in] | value | The string to be copied and used to initialize value . |
const char * paf_value_str | +( | +const struct paf_value * | +value | ) | ++ |
Retrieves the string of value
.
The returned point should not be written to, and not bee freed by the caller.
+[in] | value | A value of type string. |
value
. bool paf_value_equal | +( | +const struct paf_value * | +value_a, | +
+ | + | const struct paf_value * | +value_b | +
+ | ) | ++ |
Compares two values for equality.
+The values must be of the same type and have the same value in order to be considered equal.
+[in] | value_a | A value. |
[in] | value_b | Another (or the same) value. |
value_a
and value_b
are equal, false otherwise. struct paf_value * paf_value_clone | +( | +const struct paf_value * | +orig | ) | ++ |
Returns a copy of the supplied value.
+[in] | orig | The value to be copied. |
void paf_value_destroy | +( | +struct paf_value * | +value | ) | ++ |
Destroys a value instance.
+This function destroys the value instance and frees all the resources associated with it.
+[in] | value | The value. |
+ libpaf 1.1.1
+
+ |
+
+ libpaf |