EpcDispatcher

EpcDispatcher — publish DNS-SD services

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libepc/dispatcher.h>

enum                EpcAddressFamily;
enum                EpcCollisionHandling;
                    EpcDispatcherPrivate;
struct              EpcDispatcherClass;
struct              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);

Object Hierarchy

  GEnum
   +----EpcAddressFamily
  GEnum
   +----EpcCollisionHandling
  GObject
   +----EpcDispatcher

Properties

  "collision-handling"       EpcCollisionHandling  : Read / Write / Construct
  "cookie"                   gchar*                : Read / Write / Construct
  "name"                     gchar*                : Read / Write / Construct

Description

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

1
2
3
4
5
6
7
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);



Details

enum EpcAddressFamily

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.

EPC_ADDRESS_UNSPEC

No preferences exist. Use all address families supported.

EPC_ADDRESS_IPV4

Exclusively use IPv4 for addressing network services.

EPC_ADDRESS_IPV6

Exclusively use IPv6 for addressing network services.

enum EpcCollisionHandling

typedef enum {
  EPC_COLLISIONS_IGNORE,
  EPC_COLLISIONS_CHANGE_NAME,
  EPC_COLLISIONS_UNIQUE_SERVICE
} EpcCollisionHandling;

Various strategies for handling service name collisions.

EPC_COLLISIONS_IGNORE

Don't handle collisions at all, just fail silently.

EPC_COLLISIONS_CHANGE_NAME

Try to announce the service with another name.

EPC_COLLISIONS_UNIQUE_SERVICE

Defer own service announcement until the other service. disappears.

EpcDispatcherPrivate

typedef struct _EpcDispatcherPrivate EpcDispatcherPrivate;

Private fields of the EpcDispatcher class.


struct EpcDispatcherClass

struct EpcDispatcherClass {
};

Virtual methods of the EpcDispatcher class.


struct EpcDispatcher

struct EpcDispatcher;

Public fields of the EpcDispatcher class.


epc_dispatcher_new ()

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.

epc_dispatcher_run ()

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.

epc_dispatcher_reset ()

void                epc_dispatcher_reset                (EpcDispatcher *dispatcher);

Revokes all service announcements of this EpcDispatcher.

dispatcher :

a EpcDispatcher

epc_dispatcher_add_service ()

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

epc_dispatcher_add_service_subtype ()

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.

Note

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

epc_dispatcher_set_collision_handling ()

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


epc_dispatcher_set_cookie ()

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


epc_dispatcher_set_name ()

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

epc_dispatcher_set_service_details ()

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:

1
path=/dwarf-blog/

Note

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

epc_dispatcher_get_collision_handling ()

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


epc_dispatcher_get_cookie ()

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


epc_dispatcher_get_name ()

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.

epc_address_family_get_class ()

GEnumClass *        epc_address_family_get_class        (void);

Retrieves the GEnumClass describing the EpcAddressFamily enum.

Returns :

The GEnumClass describing EpcAddressFamily.

epc_address_family_to_string ()

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.

epc_collision_handling_get_class ()

GEnumClass *        epc_collision_handling_get_class    (void);

Retrieves the GEnumClass describing the EpcCollisionHandling enum.

Returns :

The GEnumClass describing EpcCollisionHandling.

epc_collision_handling_to_string ()

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.

Property Details

The "collision-handling" property

  "collision-handling"       EpcCollisionHandling  : Read / Write / Construct

The collision handling method to use.

Default value: EPC_COLLISIONS_CHANGE_NAME


The "cookie" property

  "cookie"                   gchar*                : Read / Write / Construct

Unique identifier of the service.

Default value: NULL


The "name" property

  "name"                     gchar*                : Read / Write / Construct

User friendly name of the service.

Default value: NULL