EpcShell: Easy Publish and Consume Reference Manual

## EpcShell EpcShell — library management functions |

## Stability Level

Private, unless otherwise indicated

## Functions

#define | EPC_DEBUG_LEVEL()
guint | epc_shell_get_debug_level ()
void | epc_shell_progress_begin ()
void | epc_shell_progress_end ()
void | epc_shell_progress_update ()
void | epc_shell_set_progress_hooks ()
guint | epc_shell_watch_avahi_client_state ()
AvahiEntryGroup * | epc_shell_create_avahi_entry_group ()
AvahiServiceBrowser * | epc_shell_create_service_browser ()
void | epc_shell_restart_avahi_client ()
const gchar * | epc_shell_get_host_name ()
void | epc_shell_watch_remove ()

## Types and Values

struct | EpcShellProgressHooks
#define | EPC_AVAHI_ERROR

## Includes

    #include <libepc/shell.h>

## Description

The methods of the EpcShell singleton are used to manage library resources.

## Functions

### EPC_DEBUG_LEVEL()

    #define EPC_DEBUG_LEVEL(level) G_UNLIKELY(epc_shell_get_debug_level () >= (level))

Checks if the library's debug level, which can be modified by setting the `EPC_DEBUG` environment variable, is above the value sepecified by `level` .

#### Parameters

level | the minimum level to check for |

#### Returns

`TRUE` if the library's debug level is above the threshold specified by `level` , and `FALSE` otherwise.

### epc_shell_get_debug_level ()

    guint
    epc_shell_get_debug_level (void);

Query the library's debug level. The debug level can be modified by setting the external `EPC_DEBUG` environment variable. In most cases the EPC_DEBUG_LEVEL macro should be used, instead of calling this checking the return value of this function.

#### Returns

The library's current debugging level.

### epc_shell_progress_begin ()

    void
    epc_shell_progress_begin (const gchar *title,
                              const gchar *message);

Call this function before starting a lengthy operation to allow the application tp provide some visual feedback during the operation, and to generally keep its UI responsive.

This function calls your “begin” hook with `title` as argument and “update” with `message` .

See also: `epc_shell_set_progress_hooks()`, epc_progress_window_install, `epc_shell_progress_update()`, epc_shell_progress_end

#### Parameters

title | the title of the lengthy operation |
message | description of the lengthy operation |

### epc_shell_progress_end ()

    void
    epc_shell_progress_end (void);

Call this function when your lengthy operation has finished.

See also: `epc_shell_set_progress_hooks()`, epc_progress_window_install, `epc_shell_progress_begin()`, epc_shell_progress_update

### epc_shell_progress_update ()

    void
    epc_shell_progress_update (gdouble percentage,
                               const gchar *message);

Called this function to inform about progress of a lengthy operation. The progress is expressed as `percentage` in the range [0..1], or -1 if the progress cannot be estimated.

See also: `epc_shell_set_progress_hooks()`, epc_progress_window_install, epc_shell_progress_begin, `epc_shell_progress_end()`

#### Parameters

percentage | current progress of the operation, or -1 |
message | a description of the current progress |

### epc_shell_set_progress_hooks ()

    void
    epc_shell_set_progress_hooks (const EpcShellProgressHooks *hooks,
                                  gpointer user_data,
                                  GDestroyNotify destroy_data);

Installs functions which are called during processing, such as generating server keys. This allows the application to indicate progress and generally keep its UI responsive. If no progress callbacks are provided, or when `NULL` is passed for `hooks` , progress messages are written to the console.

See also: EpcEntropyProgress

#### Parameters

hooks | the function table to install, or `NULL` |
user_data | custom data which shall be passed to the start hook |
destroy_data | function to call on `user_data` when the hooks are replaced |

### epc_shell_watch_avahi_client_state ()

    guint
    epc_shell_watch_avahi_client_state (AvahiClientCallback callback,
                                        gpointer user_data,
                                        GDestroyNotify destroy_data,
                                        GError **error);

Registers a function to watch state changes of the library's AvahiClient. On success the identifier of the newly created watch is returned. Pass it to `epc_shell_watch_remove()` to remove the watch. On failure it returns 0 and sets `error` . The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the Avahi library.

Usually there is no need in handling the AVAHI_CLIENT_FAILURE state for `callback`, as the callback dispatcher takes care already. This state is dispatched mostly for notification purposes.

#### Parameters

callback | a callback function |
user_data | data to pass to `callback` |
destroy_data | a function for freeing `user_data` when removing the watch |
error | return location for a GError, or `NULL` |

#### Returns

The identifier of the newly created watch, or 0 on error.

### epc_shell_create_avahi_entry_group ()

    AvahiEntryGroup *
    epc_shell_create_avahi_entry_group (AvahiEntryGroupCallback callback,
                                        gpointer user_data);

Creates a new AvahiEntryGroup for the library's shared AvahiClient. On success the newly created AvahiEntryGroup is returned, and `NULL` on failure.

#### Parameters

callback | a callback function |
user_data | data to pass to `callback` |

#### Returns

The newly created AvahiEntryGroup, or `NULL` on error.

### epc_shell_create_service_browser ()

    AvahiServiceBrowser *
    epc_shell_create_service_browser (AvahiIfIndex interface,
                                      AvahiProtocol protocol,
                                      const gchar *type,
                                      const gchar *domain,
                                      AvahiLookupFlags flags,
                                      AvahiServiceBrowserCallback callback,
                                      gpointer user_data,
                                      GError **error);

Creates a new AvahiServiceBrowser for the library's shared AvahiClient. On success the newly created AvahiEntryGroup is returned. On failure `NULL` is returned and `error` is set. The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the Avahi library.

#### Parameters

interface | the index of the network interface to watch |
protocol | the protocol of the services to watch |
type | the DNS-SD service type to watch |
domain | the DNS domain to watch, or `NULL` |
flags | flags for creating the service browser |
callback | a callback function |
user_data | data to pass to `callback` |
error | return location for a GError, or `NULL` |

#### Returns

The newly created AvahiServiceBrowser, or `NULL` on error.

### epc_shell_restart_avahi_client ()

    void
    epc_shell_restart_avahi_client (const gchar *strloc);

Requests restart of the builtin Avahi client. Use this function to react on critical failures (like AVAHI_ENTRY_GROUP_FAILURE) reported to your Avahi callbacks. The `strloc` argument is used to prevent endless restart cycles.

Do not call this function to react on AVAHI_CLIENT_FAILURE in a AvahiClientCallback. The builtin callback dispatcher deals with that situation.

#### Parameters

strloc | code location of the callee (G_STRLOC) |

### epc_shell_get_host_name ()

    const gchar *
    epc_shell_get_host_name (GError **error);

Retrieves the official host name of this machine. On failure the function returns `NULL` and sets `error` . The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the Avahi library.

#### Parameters

error | return location for a GError, or `NULL` |

#### Returns

The official host name, or `NULL` on error.

### epc_shell_watch_remove ()

    void
    epc_shell_watch_remove (guint id);

Removes the watching callback identified by `id` .

See also: `epc_shell_watch_avahi_client()`

#### Parameters

id | identifier of an watching callback |

## Types and Values

### struct EpcShellProgressHooks

    struct EpcShellProgressHooks {
      void (*begin)  (const gchar *title,
                      gpointer     user_data);
      void (*update) (gdouble      percentage,
                      const gchar *message,
                      gpointer     user_data);
      void (*end)    (gpointer     user_data);
    };

This table is used by epc_shell_set_progress_hooks to install functions allowing the library to provide feedback during processing.

See also: epc_progress_window_install

#### Members

`begin` () | the function called by epc_shell_progress_begin |
`update` () | the function called by epc_shell_progress_update |
`end` () | the function called by epc_shell_progress_end |

### EPC_AVAHI_ERROR

    #define EPC_AVAHI_ERROR (epc_avahi_error_quark ())

Error domain for Avahi operations. Errors in this domain will be Avahi error codes. See GError for information on error domains.