![]() |
![]() |
![]() |
Easy Publish and Consume Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#include <libepc/publish.h> EpcContents * (*EpcContentsHandler) (EpcPublisher *publisher
,const gchar *key
,gpointer user_data
); EpcPublisherPrivate; struct EpcPublisherClass; struct EpcPublisher; EpcPublisher * epc_publisher_new (const gchar *name
,const gchar *application
,const gchar *domain
); void epc_publisher_add (EpcPublisher *publisher
,const gchar *key
,gconstpointer data
,gssize length
); void epc_publisher_add_file (EpcPublisher *publisher
,const gchar *key
,const gchar *filename
); void epc_publisher_add_handler (EpcPublisher *publisher
,const gchar *key
,EpcContentsHandler handler
,gpointer user_data
,GDestroyNotify destroy_data
); void epc_publisher_add_bookmark (EpcPublisher *publisher
,const gchar *key
,const gchar *label
); gchar * epc_publisher_get_path (EpcPublisher *publisher
,const gchar *key
); gchar * epc_publisher_get_uri (EpcPublisher *publisher
,const gchar *key
,GError **error
); gboolean epc_publisher_has_key (EpcPublisher *publisher
,const gchar *key
); gpointer epc_publisher_lookup (EpcPublisher *publisher
,const gchar *key
); gboolean epc_publisher_remove (EpcPublisher *publisher
,const gchar *key
); GList * epc_publisher_list (EpcPublisher *publisher
,const gchar *pattern
); gboolean epc_publisher_run (EpcPublisher *publisher
,GError **error
); gboolean epc_publisher_run_async (EpcPublisher *publisher
,GError **error
); gboolean epc_publisher_quit (EpcPublisher *publisher
); gchar * epc_publisher_expand_name (const gchar *name
,GError **error
); void epc_publisher_set_auth_flags (EpcPublisher *publisher
,EpcAuthFlags flags
); void epc_publisher_set_auth_handler (EpcPublisher *publisher
,const gchar *key
,EpcAuthHandler handler
,gpointer user_data
,GDestroyNotify destroy_data
); void epc_publisher_set_collision_handling (EpcPublisher *publisher
,EpcCollisionHandling method
); void epc_publisher_set_contents_path (EpcPublisher *publisher
,const gchar *path
); void epc_publisher_set_credentials (EpcPublisher *publisher
,const gchar *certfile
,const gchar *keyfile
); void epc_publisher_set_protocol (EpcPublisher *publisher
,EpcProtocol protocol
); void epc_publisher_set_service_cookie (EpcPublisher *publisher
,const gchar *cookie
); void epc_publisher_set_service_name (EpcPublisher *publisher
,const gchar *name
); EpcAuthFlags epc_publisher_get_auth_flags (EpcPublisher *publisher
); const gchar * epc_publisher_get_certificate_file (EpcPublisher *publisher
); EpcCollisionHandling epc_publisher_get_collision_handling (EpcPublisher *publisher
); const gchar * epc_publisher_get_contents_path (EpcPublisher *publisher
); const gchar * epc_publisher_get_private_key_file (EpcPublisher *publisher
); EpcProtocol epc_publisher_get_protocol (EpcPublisher *publisher
); const gchar * epc_publisher_get_service_cookie (EpcPublisher *publisher
); const gchar * epc_publisher_get_service_domain (EpcPublisher *publisher
); const gchar * epc_publisher_get_service_name (EpcPublisher *publisher
);
"application" gchar* : Read / Write / Construct "auth-flags" EpcAuthFlags : Read / Write / Construct "certificate-file" gchar* : Read / Write / Construct "collision-handling" EpcCollisionHandling : Read / Write / Construct "contents-path" gchar* : Read / Write / Construct "private-key-file" gchar* : Read / Write / Construct "protocol" EpcProtocol : Read / Write / Construct "service-cookie" gchar* : Read / Write / Construct "service-domain" gchar* : Read / Write / Construct "service-name" gchar* : Read / Write / Construct
The EpcPublisher starts a HTTP server to publish information. To allow EpcConsumer to find the publisher it automatically publishes its contact information (host name, TCP/IP port) per DNS-SD.
In future it might use DNS-DS to notify EpcConsumer of changes.
Example 6. Publish a value
1 2 3 4 5 6 |
publisher = epc_publisher_new ("Easy Publisher Example", NULL, NULL); epc_publisher_add (publisher, "maman", "bar", -1); epc_publisher_add_file (publisher, "source-code", __FILE__); epc_publisher_run (NULL); |
EpcPublisher doesn't provide a way to explicitly publish NULL
values, as
publishing NULL
values doesn't seem very valueable in our scenario: Usually
you want to "publish" NULL
values to express, that your application doesn't
have any meaningful information for the requested identifier. By "publishing"
a NULL
value essentially you say "this information does not exist". So
publishing NULL
values is not different from not publishing any value at
all or rejected access to some values. Without explicitly inspecting the
details for not receiving a value, a consumer calling epc_consumer_lookup()
has no chance to distinguish between the cases "never published", "network
problem", "authorization rejected", "no meaningful value available".
So if feel like publishing a NULL
value, just remove the key in question
from the EpcPublisher by calling epc_publisher_remove()
. When using a
custom EpcContentsHandler an alternate approach is returning NULL
from
that handler. In that case the EpcPublisher will behave exactly the same,
as if the value has been removed.
EpcContents * (*EpcContentsHandler) (EpcPublisher *publisher
,const gchar *key
,gpointer user_data
);
This callback is used to generate custom contents published with the
epc_publisher_add_handler function. The arguments passed are the same as
passed to epc_publisher_add_handler. The EpcPublisher will decrease the
reference count of the returned buffer after deliving it. It's valid to
return NULL
in situations were no contents can be generated.
|
the EpcPublisher |
|
the unique key |
|
user data set when the signal handler was installed |
Returns : |
The EpcContents buffer for this publication, or NULL . |
typedef struct _EpcPublisherPrivate EpcPublisherPrivate;
Private fields of the EpcPublisher class.
EpcPublisher * epc_publisher_new (const gchar *name
,const gchar *application
,const gchar *domain
);
Creates a new EpcPublisher object. The publisher announces its service
per DNS-SD to the DNS domain specified by domain
, using name
as service
name. The service type is derived from application
. When NULL
is passed
for application
the value returned by g_get_prgname()
is used. See
epc_service_type_new()
for details.
|
the human friendly service name, or NULL
|
|
application name used for DNS-SD service type, or NULL
|
|
the DNS domain for announcing the service, or NULL
|
Returns : |
The newly created EpcPublisher object. |
void epc_publisher_add (EpcPublisher *publisher
,const gchar *key
,gconstpointer data
,gssize length
);
Publishes a new value on the EpcPublisher using the unique key
for
addressing. When -1 is passed for length
, data
is expected to be a
null-terminated string and its length in bytes is determined automatically
using strlen
.
Values published by the EpcPublisher can be arbitrary data, possibly
including null characters in the middle. The kind of data associated
with a key
is chosen by the application providing values and should
be specified separately.
However, when publishing plain text it is strongly recommended to use UTF-8 encoding to avoid internationalization issues.
|
a EpcPublisher |
|
the key for addressing the value |
|
the value to publish |
|
the length of data in bytes, or -1 if data is a null-terminated string. |
void epc_publisher_add_file (EpcPublisher *publisher
,const gchar *key
,const gchar *filename
);
Publishes a local file on the EpcPublisher using the unique
key
for addressing. The publisher delivers the current contents
of the file at the time of access.
|
a EpcPublisher |
|
the key for addressing the file |
|
the name of the file to publish |
void epc_publisher_add_handler (EpcPublisher *publisher
,const gchar *key
,EpcContentsHandler handler
,gpointer user_data
,GDestroyNotify destroy_data
);
Publishes contents on the EpcPublisher which are generated by a custom EpcContentsHandler callback. This is the most flexible method for publishing information.
The handler
is called on every request matching key
.
When called, publisher
, key
and user_data
are passed to the handler
.
When replacing or deleting the resource referenced by key
,
or when the the Publisher is destroyed, the function
described by destroy_data
is called with user_data
as argument.
|
a EpcPublisher |
|
the key for addressing the contents |
|
the EpcContentsHandler for handling this contents |
|
data to pass on handler calls |
|
a function for releasing user_data
|
void epc_publisher_add_bookmark (EpcPublisher *publisher
,const gchar *key
,const gchar *label
);
Installs a dynamic HTTP (respectively HTTPS) bookmark for key
.
This allows consumption of EpcPublisher resources by foreign
applications that support ZeroConf bookmarks, but not libepc.
This is useful for instance for publishing media playlists.
Passing NULL
as key
installs a bookmark for the root context of the
builtin web server. When passing NULL
as label
the publisher's name
is used as bookmark label.
Dynamic bookmarks must be unique within the service domain.
Therefore the label
will get modified on name collisions.
This should be called after adding the resource identified by key
,
not before. For instance, after calling epc_publisher_add()
.
gchar * epc_publisher_get_path (EpcPublisher *publisher
,const gchar *key
);
Queries the path component of the URI used to publish the resource
associated with key
. This is useful when referencing keys in published
resources. Passing NULL
as key
retrieve the path of the root context.
|
a EpcPublisher |
|
the resource key to inspect, or NULL . |
Returns : |
The resource path for key . |
gchar * epc_publisher_get_uri (EpcPublisher *publisher
,const gchar *key
,GError **error
);
Queries the URI used to publish the resource associated with key
.
This is useful when referencing keys in published resources. When
passing NULL
the publisher's base URI is returned.
The function fails if the publisher's host name cannot be retrieved.
In that case NULL
is returned and error
is set. The error domain is
EPC_AVAHI_ERROR. Possible error codes are those of the
Avahi library.
|
a EpcPublisher |
|
the resource key to inspect, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
The fully qualified URI for key , or NULL on error. |
gboolean epc_publisher_has_key (EpcPublisher *publisher
,const gchar *key
);
Checks if information is published for key
.
This function allows to use the publisher as local key/value store, which is useful for instance to prevent accidental key collisions.
See also: epc_publisher_lookup.
|
a EcpPublisher |
|
the key for addressing contents |
Returns : |
TRUE when the publisher has information for key ,
and FALSE otherwise. |
gpointer epc_publisher_lookup (EpcPublisher *publisher
,const gchar *key
);
Looks up the user_data passed to epc_publisher_add_handler()
for key
.
Returns NULL
if the specified key
doesn't exist or wasn't published
with epc_publisher_add_handler()
.
This function allows to use the publisher as local key/value store, which is useful for instance to prevent accidental key collisions.
See also: epc_publisher_has_key.
|
a EcpPublisher |
|
the key for addressing contents |
Returns : |
The user_data associated with key , or NULL . |
gboolean epc_publisher_remove (EpcPublisher *publisher
,const gchar *key
);
Removes a key and its associated contents from a EpcPublisher.
|
a EpcPublisher |
|
the key for addressing the contents |
Returns : |
TRUE if the key was found and removed from the EpcPublisher. |
GList * epc_publisher_list (EpcPublisher *publisher
,const gchar *pattern
);
Matches published keys against patterns containing '*' (wildcard) and '?'
(joker). Passing NULL
as pattern
is equivalent to passing "*" and returns
all published keys. This function is useful for generating dynamic resource
listings in other formats than libepc's specific format. See GPatternSpec
for information about glob-style patterns.
If the call was successful, a list of keys matching pattern
is returned.
If the call was not successful, it returns NULL
.
The returned list should be freed when no longer needed:
g_list_foreach (keys, (GFunc) g_free, NULL); g_list_free (keys);
See also epc_consumer_list()
for builtin listing capabilities.
|
a EpcPublisher |
|
a glob-style pattern, or NULL
|
Returns : |
A newly allocated list of keys, or NULL when an error occurred. |
gboolean epc_publisher_run (EpcPublisher *publisher
,GError **error
);
Starts the server component of the EpcPublisher and blocks until it is
shutdown using epc_publisher_quit()
. If the server could not be started, the
function returns FALSE
and sets error
. The error domain is
EPC_AVAHI_ERROR. Possible error codes are those of the
Avahi library.
When starting the publisher in HTTPS mode for the first time self-signed
keys must be generated. Generating secure keys needs some time,
so it is recommended to call epc_progress_window_install()
, or
epc_shell_set_progress_hooks()
to provide visual feedback during that
operation. Key generation takes place in a separate background thread and
the calling thread waits in a GMainLoop. Therefore the UI can remain
responsive when generating keys.
To start the server without blocking call epc_publisher_run_async()
.
|
a EpcPublisher |
|
return location for a GError, or NULL
|
Returns : |
TRUE when the publisher was successfully started,
FALSE if an error occurred. |
gboolean epc_publisher_run_async (EpcPublisher *publisher
,GError **error
);
Starts the server component of the EpcPublisher without blocking. If the
server could not be started then the function returns FALSE
and sets error
. The
error domain is EPC_AVAHI_ERROR. Possible error codes are those of the
Avahi library.
To stop the server component call epc_publisher_quit()
.
See epc_publisher_run()
for additional information.
|
a EpcPublisher |
|
return location for a GError, or NULL
|
Returns : |
TRUE when the publisher was successfully started,
FALSE if an error occurred. |
gboolean epc_publisher_quit (EpcPublisher *publisher
);
Stops the server component of the EpcPublisher started with
epc_publisher_run()
or epc_publisher_run_async. The functions
returns TRUE
when the built-in server was running and had to
be stopped. If the server wasn't running the function returns
FALSE
.
|
a EpcPublisher |
Returns : |
TRUE when the server had to be stopped, and FALSE otherwise. |
gchar * epc_publisher_expand_name (const gchar *name
,GError **error
);
Expands all known placeholders in name
. Supported placeholders are:
a
: the program name as returned by g_get_application_name()
h
: the machine's host name in title caseu
: the user's login name in title caseU
: the user's real name
The function fails when the host name cannot looked up. In that case NULL
is returned and error
is set. The error domain is EPC_AVAHI_ERROR.
Possible error codes are those of the Avahi library.
void epc_publisher_set_auth_flags (EpcPublisher *publisher
,EpcAuthFlags flags
);
Changes the authentication settings the publisher uses
when epc_publisher_set_auth_handler()
is used.
See "auth-flags" for details.
|
a EpcPublisher |
|
new authentication settings |
void epc_publisher_set_auth_handler (EpcPublisher *publisher
,const gchar *key
,EpcAuthHandler handler
,gpointer user_data
,GDestroyNotify destroy_data
);
Installs an authentication handler for the specified key
.
Passing NULL
as key
installs a fallback handler for all resources.
The handler
is called on every request matching key
. On this call
a temporary EpcAuthContext and user_data
are passed to the handler
.
The EpcAuthContext references the publisher
and key
passed here.
When replacing or deleting the resource referenced by key
, or when
the publisher is destroyed, the function
described by destroy_data
is called with user_data
as argument.
This should be called after adding the resource identified by key
,
not before. For instance, after calling epc_publisher_add()
.
See also epc_publisher_set_auth_flags()
.
|
a EpcPublisher |
|
the key of the resource to protect, or NULL
|
|
the EpcAuthHandler to connect |
|
data to pass on handler calls |
|
a function for releasing user_data
|
void epc_publisher_set_collision_handling (EpcPublisher *publisher
,EpcCollisionHandling method
);
Changes the collision handling strategy the publisher uses. See "collision-handling" for details.
|
a EpcPublisher |
|
the new strategy |
Since 0.3.1
void epc_publisher_set_contents_path (EpcPublisher *publisher
,const gchar *path
);
Changes the server path used for publishing contents. See "contents-path" for details.
|
a EpcPublisher |
|
the new contents path |
void epc_publisher_set_credentials (EpcPublisher *publisher
,const gchar *certfile
,const gchar *keyfile
);
Changes the file names of the PEM encoded TLS credentials the publisher use for its services, when the transport "protocol" is EPC_PROTOCOL_HTTPS.
See "certificate-file" and "private-key-file" for details.
|
a EpcPublisher |
|
file name of the server certificate |
|
file name of the private key |
void epc_publisher_set_protocol (EpcPublisher *publisher
,EpcProtocol protocol
);
Changes the transport protocol the publisher uses. See "protocol" for details.
|
a EpcPublisher |
|
the transport protocol |
void epc_publisher_set_service_cookie (EpcPublisher *publisher
,const gchar *cookie
);
Changes the unique identifier of the service. See "service-cookie" for details.
|
a EpcPublisher |
|
the new service identifier, or NULL
|
Since 0.3.1
void epc_publisher_set_service_name (EpcPublisher *publisher
,const gchar *name
);
Changes the human friendly name this EpcPublisher uses to announce its service. See "service-name" for details.
|
a EpcPublisher |
|
the new name of this EpcPublisher |
EpcAuthFlags epc_publisher_get_auth_flags (EpcPublisher *publisher
);
Queries the current authentication settings of the publisher. See "auth-flags" for details.
|
a EpcPublisher |
Returns : |
The authentication settings of the publisher, or EPC_AUTH_DEFAULT on error. |
const gchar * epc_publisher_get_certificate_file (EpcPublisher *publisher
);
Queries the file name of the PEM encoded server certificate. See "certificate-file" for details.
|
a EpcPublisher |
Returns : |
The certificate's file name, or NULL . |
EpcCollisionHandling epc_publisher_get_collision_handling
(EpcPublisher *publisher
);
Queries the collision handling strategy the publisher uses. See "collision-handling" for details.
|
a EpcPublisher |
Returns : |
The publisher's collision handling strategy, or EPC_COLLISIONS_IGNORE on error. |
Since 0.3.1
const gchar * epc_publisher_get_contents_path (EpcPublisher *publisher
);
Queries the server path used for publishing contents. See "contents-path" for details.
|
a EpcPublisher |
Returns : |
The server's contents path. |
const gchar * epc_publisher_get_private_key_file (EpcPublisher *publisher
);
Queries the file name of the PEM encoded private server key. See "private-key-file" for details.
|
a EpcPublisher |
Returns : |
The private key's file name, or NULL . |
EpcProtocol epc_publisher_get_protocol (EpcPublisher *publisher
);
Queries the transport protocol the publisher uses. See "protocol" for details.
|
a EpcPublisher |
Returns : |
The transport protocol the publisher uses, or EPC_PROTOCOL_UNKNOWN on error. |
const gchar * epc_publisher_get_service_cookie (EpcPublisher *publisher
);
Queries the unique identifier of the service. See "service-cookie" for details.
|
a EpcPublisher |
Returns : |
The unique identifier of the service, or NULL on error. |
Since 0.3.1
const gchar * epc_publisher_get_service_domain (EpcPublisher *publisher
);
Queries the DNS domain for which this EpcPublisher announces its service. See "domain" for details.
|
a EpcPublisher |
Returns : |
The DNS-SD domain of this EpcPublisher, or NULL . |
const gchar * epc_publisher_get_service_name (EpcPublisher *publisher
);
Queries the human friendly name this EpcPublisher uses to announce its service. See "name" for details.
|
a EpcPublisher |
Returns : |
The human friendly name of this EpcPublisher. |
"application"
property "application" gchar* : Read / Write / Construct
Program name for deriving the service type.
Default value: NULL
"auth-flags"
property"auth-flags" EpcAuthFlags : Read / Write / Construct
The authentication settings to use.
"certificate-file"
property "certificate-file" gchar* : Read / Write / Construct
File name for the PEM encoded server certificate.
Default value: NULL
"collision-handling"
property"collision-handling" EpcCollisionHandling : Read / Write / Construct
The collision handling strategy the publisher uses.
Default value: EPC_COLLISIONS_CHANGE_NAME
Since 0.3.1
"contents-path"
property "contents-path" gchar* : Read / Write / Construct
The built-in server path for publishing resources.
Default value: "/contents"
"private-key-file"
property "private-key-file" gchar* : Read / Write / Construct
File name for the PEM encoded private server key.
Default value: NULL
"protocol"
property"protocol" EpcProtocol : Read / Write / Construct
The transport protocol the publisher uses.
Default value: EPC_PROTOCOL_HTTPS
"service-cookie"
property "service-cookie" gchar* : Read / Write / Construct
Unique identifier of the service. This cookie is used for implementing
EPC_COLLISIONS_UNIQUE_SERVICE, and usually is a UUID or the MD5/SHA1/...
checksum of a central document. When passing NULL
, but using the
EPC_COLLISIONS_UNIQUE_SERVICE strategy a time based UUID is
generated and used as service identifier.
Default value: NULL
Since 0.3.1
"service-domain"
property "service-domain" gchar* : Read / Write / Construct
Internet domain for publishing the service.
Default value: NULL