EpcDispatcher: Easy Publish and Consume Reference Manual

## EpcDispatcher EpcDispatcher — publish DNS-SD services |

## Stability Level

Unstable, unless otherwise indicated

## Functions

EpcDispatcher * | epc_dispatcher_new ()
gboolean | epc_dispatcher_run ()
void | epc_dispatcher_reset ()
void | epc_dispatcher_add_service ()
void | epc_dispatcher_add_service_subtype ()
void | epc_dispatcher_set_collision_handling ()
void | epc_dispatcher_set_cookie ()
void | epc_dispatcher_set_name ()
void | epc_dispatcher_set_service_details ()
EpcCollisionHandling | epc_dispatcher_get_collision_handling ()
const gchar * | epc_dispatcher_get_cookie ()
const gchar * | epc_dispatcher_get_name ()
GEnumClass * | epc_address_family_get_class ()
const gchar * | epc_address_family_to_string ()
GEnumClass * | epc_collision_handling_get_class ()
const gchar * | epc_collision_handling_to_string ()

## Properties

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

## Types and Values

enum | EpcAddressFamily
enum | EpcCollisionHandling
| EpcDispatcherPrivate
struct | EpcDispatcherClass
struct | EpcDispatcher

## Object Hierarchy

        GEnum
        ├── EpcAddressFamily
        ╰── EpcCollisionHandling
        GObject
        ╰── EpcDispatcher

## Includes

    #include <libepc/dispatcher.h>

## 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);

## Functions

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

This function will fail silently, when the service specified by `type` hasn't been registered yet.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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”.

#### Parameters

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/

This function will fail silently, when the service specified by `type` hasn't been registered yet.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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”.

#### Parameters

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.

#### Parameters

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.

#### Parameters

value | a EpcCollisionHandling value |

#### Returns

The string representation of `value` , or `NULL`.

## Types and Values

### enum EpcAddressFamily

The address family to use for contacting network services.

#### Members

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

Various strategies for handling service name collisions.

#### Members

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.

#### Members

### struct EpcDispatcherClass

    struct EpcDispatcherClass {
    };

Virtual methods of the EpcDispatcher class.

### struct EpcDispatcher

    struct EpcDispatcher;

Public fields of the EpcDispatcher class.

## Property Details

### The `“collision-handling”` property

      “collision-handling”       EpcCollisionHandling

The collision handling method to use.

Flags: Read / Write / Construct

Default value: EPC_COLLISIONS_CHANGE_NAME

### The `“cookie”` property

      “cookie”                   gchar *

Unique identifier of the service.

Flags: Read / Write / Construct

Default value: NULL

### The `“name”` property

      “name”                     gchar *

User friendly name of the service.

Flags: Read / Write / Construct

Default value: NULL