|
|
|
Easy Publish and Consume Reference Manual | |
|---|---|---|---|---|
#include <libepc/publish.h>
EpcPublisherPrivate;
EpcPublisherClass;
EpcPublisher;
EpcPublisher* epc_publisher_new (const gchar *name,
const gchar *application,
const gchar *domain);
void epc_publisher_add (EpcPublisher *publisher,
const gchar *key,
const gchar *value,
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);
gboolean epc_publisher_remove (EpcPublisher *publisher,
const gchar *key);
void epc_publisher_run (EpcPublisher *publisher);
void epc_publisher_run_async (EpcPublisher *publisher);
void epc_publisher_quit (EpcPublisher *publisher);
void epc_publisher_set_auth_handler (EpcPublisher *publisher,
const gchar *key,
EpcAuthHandler handler,
gpointer user_data,
GDestroyNotify destroy_data);
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_name (EpcPublisher *publisher,
const gchar *name);
const gchar* epc_publisher_get_certificate_file (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_name (EpcPublisher *publisher);
const gchar* epc_publisher_get_service_domain (EpcPublisher *publisher);
"application" gchar* : Read / Write / Construct "certificate-file" gchar* : Read / Write / Construct "private-key-file" gchar* : Read / Write / Construct "protocol" EpcProtocol : 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 7. Publish a value
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 ();
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.
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.
name : |
the human friendly service name, or NULL
|
application : |
application name used for DNS-SD service type, or NULL
|
domain : |
the DNS domain for announcing the service, or NULL
|
| Returns : | The newly created EpcPublisher object. |
void epc_publisher_add (EpcPublisher *publisher, const gchar *key, const gchar *value, gssize length);
Publishes a new value on the EpcPublisher using the unique key for
addressing. When -1 is passed for length, value 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 has
to be specified separately.
However, when publishing plain text it is strongly recommended to use UTF-8 encoding to avoid internationalization issues.
publisher : |
a EpcPublisher |
key : |
the key for addressing the value |
value : |
the value to publish |
length : |
the length of value in bytes, or -1.
|
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 content
of the file at the time of access.
publisher : |
a EpcPublisher |
key : |
the key for addressing the file |
filename : |
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.
publisher : |
a EpcPublisher |
key : |
the key for addressing the content |
handler : |
the EpcContentsHandler for handling this content |
user_data : |
data to pass on handler calls
|
destroy_data : |
a function for releasing user_data
|
gboolean epc_publisher_remove (EpcPublisher *publisher, const gchar *key);
Removes a key and its associated content from a EpcPublisher.
publisher : |
a EpcPublisher |
key : |
the key for addressing the content |
| Returns : | TRUE if the key was found and removed from the EpcPublisher.
|
void epc_publisher_run (EpcPublisher *publisher);
Starts the server component of the EpcPublisher and blocks until it is shutdown using epc_publisher_quit.
To start the server without blocking call epc_publisher_run_async.
publisher : |
a EpcPublisher |
void epc_publisher_run_async (EpcPublisher *publisher);
Starts the server component of the EpcPublisher without blocking. To start the server without blocking call epc_publisher_run_async. To stop the server component call epc_publisher_quit.
publisher : |
a EpcPublisher |
void epc_publisher_quit (EpcPublisher *publisher);
Stops the server component of the EpcPublisher started with epc_publisher_run or epc_publisher_run_async.
publisher : |
a EpcPublisher |
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.
publisher : |
a EpcPublisher |
key : |
the key of the resource to protect, or NULL
|
handler : |
the EpcAuthHandler to connect |
user_data : |
data to pass on handler calls
|
destroy_data : |
a function for releasing user_data
|
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.
publisher : |
a EpcPublisher |
certfile : |
file name of the server certificate |
keyfile : |
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.
publisher : |
a EpcPublisher |
protocol : |
the transport protocol |
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.
publisher : |
a EpcPublisher |
name : |
the new name of this EpcPublisher |
const gchar* epc_publisher_get_certificate_file (EpcPublisher *publisher);
Queries the file name of the PEM encoded server certificate. See "certificate-file" for details.
publisher : |
a EpcPublisher |
| Returns : | The certificate's file name, or NULL.
|
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.
publisher : |
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.
publisher : |
a EpcPublisher |
| Returns : | The transport protocol the publisher uses, or EPC_PROTOCOL_UNKNOWN. |
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.
publisher : |
a EpcPublisher |
| Returns : | The human friendly name of this EpcPublisher. |
const gchar* epc_publisher_get_service_domain (EpcPublisher *publisher);
Queries the DNS domain for which this EpcPublisher announces its service. See "domain" for details.
publisher : |
a EpcPublisher |
| Returns : | The DNS-SD domain of this EpcPublisher, or NULL.
|
"application" property"application" gchar* : Read / Write / Construct
Program name for deriving the service type.
Default value: NULL
"certificate-file" property"certificate-file" gchar* : Read / Write / Construct
File name for the PEM encoded server certificate.
Default value: NULL
"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-domain" property"service-domain" gchar* : Read / Write / Construct
Internet domain for publishing the service.
Default value: NULL
"service-name" property"service-name" gchar* : Read / Write / Construct
User friendly name for the service.
Default value: NULL