![]() |
![]() |
![]() |
Easy Publish and Consume Reference Manual | ![]() |
---|---|---|---|---|
#include <libepc/dispatcher.h> enum EpcAddressFamily; enum EpcCollisionHandling; EpcDispatcherPrivate; EpcDispatcherClass; EpcDispatcher; EpcDispatcher* epc_dispatcher_new (const gchar *name); gboolean epc_dispatcher_run (EpcDispatcher *dispatcher, GError **error); void epc_dispatcher_reset (EpcDispatcher *dispatcher); void epc_dispatcher_add_service (EpcDispatcher *dispatcher, EpcAddressFamily protocol, const gchar *type, const gchar *domain, const gchar *host, guint16 port, ...); void epc_dispatcher_add_service_subtype (EpcDispatcher *dispatcher, const gchar *type, const gchar *subtype); void epc_dispatcher_set_collision_handling (EpcDispatcher *dispatcher, EpcCollisionHandling method); void epc_dispatcher_set_cookie (EpcDispatcher *dispatcher, const gchar *cookie); void epc_dispatcher_set_name (EpcDispatcher *dispatcher, const gchar *name); void epc_dispatcher_set_service_details (EpcDispatcher *dispatcher, const gchar *type, ...); EpcCollisionHandling epc_dispatcher_get_collision_handling (EpcDispatcher *dispatcher); const gchar* epc_dispatcher_get_cookie (EpcDispatcher *dispatcher); const gchar* epc_dispatcher_get_name (EpcDispatcher *dispatcher); GEnumClass* epc_address_family_get_class (void); const gchar* epc_address_family_to_string (EpcAddressFamily value); GEnumClass* epc_collision_handling_get_class (void); const gchar* epc_collision_handling_to_string (EpcCollisionHandling value);
"collision-handling" EpcCollisionHandling : Read / Write / Construct "cookie" gchar* : Read / Write / Construct "name" gchar* : Read / Write / Construct
The EpcDispatcher object provides an easy method for publishing DNS-SD services. Unlike established APIs like Avahi or HOWL the EpcDispatcher doesn't expose any state changes reported by the DNS-SD daemon, but instead tries to handle them automatically. Such state changes include, for instance, name collisions or a restart of the DNS-SD daemon.
Example 7. Publish a printing service
dispatcher = epc_dispatcher_new ("Dead Tree Desecrator"); epc_dispatcher_add_service (dispatcher, EPC_ADDRESS_IPV4, "_ipp._tcp", NULL, NULL, 651, "path=/printers", NULL); epc_dispatcher_add_service (dispatcher, EPC_ADDRESS_UNSPEC, "_duplex._sub._printer._tcp", NULL, NULL, 515, NULL);
typedef enum { EPC_ADDRESS_UNSPEC = AF_UNSPEC, EPC_ADDRESS_IPV4 = AF_INET, EPC_ADDRESS_IPV6 = AF_INET6 } EpcAddressFamily;
The address family to use for contacting network services.
typedef enum { EPC_COLLISIONS_IGNORE, EPC_COLLISIONS_CHANGE_NAME, EPC_COLLISIONS_UNIQUE_SERVICE } EpcCollisionHandling;
Various strategies for handling service name collisions.
typedef struct _EpcDispatcherPrivate EpcDispatcherPrivate;
Private fields of the EpcDispatcher class.
typedef struct { } EpcDispatcherClass;
Virtual methods of the EpcDispatcher class.
typedef struct _EpcDispatcher EpcDispatcher;
Public fields of the EpcDispatcher class.
EpcDispatcher* epc_dispatcher_new (const gchar *name);
Creates a new EpcDispatcher object for announcing a DNS-SD service. The service is announced on all network interfaces.
Call epc_dispatcher_add_service()
to actually announce a service.
name : |
the human friendly name of the service |
Returns : | the newly created EpcDispatcher object. |
gboolean epc_dispatcher_run (EpcDispatcher *dispatcher, GError **error);
Starts the Avahi client of the EpcDispatcher. If the
client was not started, the function returns FALSE
and sets error
. The
error domain is EPC_AVAHI_ERROR. Possible error codes are those of the
Avahi library.
dispatcher : |
a EpcDispatcher |
error : |
return location for a GError, or NULL
|
Returns : | TRUE when the dispatcher was started successfully,
FALSE if an error occurred.
|
void epc_dispatcher_reset (EpcDispatcher *dispatcher);
Revokes all service announcements of this EpcDispatcher.
dispatcher : |
a EpcDispatcher |
void epc_dispatcher_add_service (EpcDispatcher *dispatcher, EpcAddressFamily protocol, const gchar *type, const gchar *domain, const gchar *host, guint16 port, ...);
Announces a TCP/IP service via DNS-SD.
The service type
shall be a well-known DNS-SD service type as listed on
http://www.dns-sd.org/ServiceTypes.html. This function tries
to announce both the base service type and the sub service type when the
service name contains more than just one dot: Passing "_anon._sub._ftp._tcp"
for type
will announce the services "_ftp._tcp" and "_anon._sub._ftp._tcp".
The function can be called more than once. Is this necessary when the server provides different access methods. For instance a web server could provide HTTP and encrypted HTTPS services at the same time. Calling this function multiple times also is useful for servers providing the same service at different, but not all network interfaces of the host.
When passing NULL
for domain
, the service is announced within the local
network only, otherwise it is announced at the specified DNS domain. The
responsible server must be
configured to support DNS-SD.
Pass NULL
for host
to use the official host name of the machine to announce
the service. On machines with multiple DNS entries you might want to explictly
choose a fully qualified DNS name to announce the service.
dispatcher : |
a EpcDispatcher |
protocol : |
the EpcAddressFamily this service supports |
type : |
the machine friendly name of the service |
domain : |
the DNS domain for the announcement, or NULL
|
host : |
the fully qualified host name of the service, or NULL
|
port : |
the TCP/IP port of the service |
... : |
an optional list of TXT records, terminated by NULL
|
void epc_dispatcher_add_service_subtype (EpcDispatcher *dispatcher, const gchar *type, const gchar *subtype);
Announces an additional sub service for a registered DNS-SD service.
This function will fail silently, when the service specified by
type
hasn't been registered yet.
dispatcher : |
a EpcDispatcher |
type : |
the base service type |
subtype : |
the sub service type |
void epc_dispatcher_set_collision_handling (EpcDispatcher *dispatcher, EpcCollisionHandling method);
Changes the collision handling strategy the dispatcher uses. See "collision-handling" for details.
dispatcher : |
a EpcDispatcher |
method : |
the new strategy |
Since 0.3.1
void epc_dispatcher_set_cookie (EpcDispatcher *dispatcher, const gchar *cookie);
Changes the unique identifier of the service. See "cookie" for details.
dispatcher : |
a EpcDispatcher |
cookie : |
the new service identifier, or NULL
|
Since 0.3.1
void epc_dispatcher_set_name (EpcDispatcher *dispatcher, const gchar *name);
Changes the user friendly name used for announcing services. See "name".
dispatcher : |
a EpcDispatcher |
name : |
the new user friendly name |
void epc_dispatcher_set_service_details (EpcDispatcher *dispatcher, const gchar *type, ...);
Updates the list of TXT records for a registered DNS-SD service. The TXT records are specified by the service type and usually have the form of key-value pairs:
path=/dwarf-blog/
This function will fail silently, when the service specified by
type
hasn't been registered yet.
dispatcher : |
a EpcDispatcher |
type : |
the service type |
... : |
a list of TXT records, terminated by NULL
|
EpcCollisionHandling epc_dispatcher_get_collision_handling (EpcDispatcher *dispatcher);
Queries the collision handling strategy the dispatcher uses. See "collision-handling" for details.
dispatcher : |
a EpcDispatcher |
Returns : | The dispatcher's collision handling strategy, or EPC_COLLISIONS_IGNORE on error. |
Since 0.3.1
const gchar* epc_dispatcher_get_cookie (EpcDispatcher *dispatcher);
Queries the unique identifier of the service. See "cookie" for details.
dispatcher : |
a EpcDispatcher |
Returns : | The unique identifier of the service, or NULL on error.
|
Since 0.3.1
const gchar* epc_dispatcher_get_name (EpcDispatcher *dispatcher);
Queries the user friendly name used for announcing services. See "name".
dispatcher : |
a EpcDispatcher |
Returns : | The user friendly name of the service. |
GEnumClass* epc_address_family_get_class (void);
Retrieves the GEnumClass describing the EpcAddressFamily enum.
Returns : | The GEnumClass describing EpcAddressFamily. |
const gchar* epc_address_family_to_string (EpcAddressFamily value);
Retrieves the name of a EpcAddressFamily value
, or NULL
when value
is invalid.
value : |
a EpcAddressFamily value |
Returns : | The string representation of value , or NULL .
|
GEnumClass* epc_collision_handling_get_class (void);
Retrieves the GEnumClass describing the EpcCollisionHandling enum.
Returns : | The GEnumClass describing EpcCollisionHandling. |
const gchar* epc_collision_handling_to_string (EpcCollisionHandling value);
Retrieves the name of a EpcCollisionHandling value
, or NULL
when value
is invalid.
value : |
a EpcCollisionHandling value |
Returns : | The string representation of value , or NULL .
|
"collision-handling"
property"collision-handling" EpcCollisionHandling : Read / Write / Construct
The collision handling method to use.
Default value: EPC_COLLISIONS_CHANGE_NAME
"cookie"
property"cookie" gchar* : Read / Write / Construct
Unique identifier of the service.
Default value: NULL
"name"
property"name" gchar* : Read / Write / Construct
User friendly name of the service.
Default value: NULL