To interact with the Rendezvous network, first you create a session by calling sw_rendezvous_init
or sw_rendezvous_init_with_salt
. Then you set up reply functions by calling sw_rendezvous_publish
, sw_rendezvous_browse_domains
, sw_rendezvous_browse_services
, and/or sw_rendezvous_resolve
. The reply functions are callbacks that you write, through which your code is notified that new services have become available, an attempt to publish a service succeeded or failed, etc. Finally you call sw_rendezvous_run
to yield the CPU to Howl and enable your reply functions to be called as those events occur.
These functions are not thread-safe. Because they involve calling reply functions in response to asynchronous events, there can be conflicts when using them within a GUI, which has its own event loop.
Here are two solutions:
1. Put all Rendezvous code into one thread.
2. Or, start the session with sw_rendezvous_init_with_salt
, with an sw_salt structure that specifies a GUI context. See sw_salt for more information.
sw_result
sw_rendezvous_init
(
sw_rendezvous *session)
session
is allocated by the user and filled in by Howl.
The session created by sw_rendezvous_init
is not thread-safe and is not suitable for use inside a GUI thread.
In a session created by sw_rendezvous_init
, after calling each rendezvous function that calls a reply function, you must call sw_rendezvous_run
to yield the CPU. Only then will the reply function be called. To create a session suitable for use inside a GUI thread, see sw_rendezvous_init_with_salt
.
int run_complete_rendezvous_session(void)
{
sw_rendezvous session;
if (sw_rendezvous_init(&session) != SW_OKAY)
{
fprintf(stderr, "init failed\n");
return -1;
}
.
. // set up reply functions here
.
sw_rendezvous_run(session);
}
sw_rendezvous_fina
, sw_rendezvous_run
, sw_rendezvous_init_with_salt
sw_result
sw_rendezvous_init_with_salt
(
sw_rendezvous *session,
sw_salt salt)
session
is allocated by the user and filled in by Howl.
The session created by sw_rendezvous_init_with_salt
is not thread-safe. Depending on the contents of salt
, it can be suitable for use inside a GUI thread.
int run_complete_rendezvous_session(void)
{
sw_rendezvous session;
sw_salt salt;
if (sw_salt_init(&salt, SW_CONTEXT_GUI, argc, argv) != SW_OKAY)
{
fprintf(stderr, "salt init failed\n");
return -1;
}
if (sw_rendezvous_init_with_salt(&session, salt) != SW_OKAY)
{
fprintf(stderr, "init failed\n");
return -1;
}
.
. // set up reply functions here
.
}
sw_rendezvous_fina
, sw_rendezvous_run
, sw_rendezvous_init_with_salt
sw_result
sw_rendezvous_fina
(
sw_rendezvous session)
int run_complete_rendezvous_session(void)
{
sw_rendezvous session;
if (sw_rendezvous_init(&session) != SW_OKAY)
{
fprintf(stderr, "init failed\n");
return -1;
}
.
. // session work here
.
sw_rendezvous_fina(session);
...
}
sw_rendezvous_init
, sw_rendezvous_init_with_salt
sw_result
sw_rendezvous_publish
(
sw_rendezvous session,
sw_const_string name,
sw_const_string type,
sw_const_string domain,
sw_port port,
sw_const_string attrs,
sw_rendezvous_publish_handler handler,
sw_rendezvous_publish_reply
reply,
sw_opaque extra,
sw_rendezvous_publish_id *id)
sw_rendezvous_publish
, the service's availability is known to all processes on the Rendezvous network.
session
: The Rendezvous session.
name
: The name of the service to publish. UTF-8 encoded.
type
: The name of the type of the service, for example "_http._tcp.". UTF-8 encoded. See zeroconf.org and RFC2782 for details on the format of service type names.
domain
: The name of the Zeroconf domain. UTF-8 encoded. Pass a NULL for the default domain, which is ".local".
port
: The port number of the socket that the service can be contacted on. For example, an FTP server should be published as residing at port 21.
attrs
: An arbitrary string containing parameters for the service. The format of the string is service-specific.
handler
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. handler
is analogous to the C++ this
pointer, and is suitable for use as an object pointer when writing an object-oriented interface to Howl.
reply
: A pointer to the reply function. In reply to the publish call, the Howl system service calls the reply function to return the status of the publish operation. A single call to sw_rendezvous_publish
may trigger the reply function to be called multiple times.
extra
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. extra
is analogous to an argument passed to an object-oriented method call, in addition to the implicit "this
" argument supplied by handler
.
id
: Identifies the specific call to sw_rendezvous_publish
, enabling other functions, like the reply function, to refer to the present attempt to publish. id
is allocated by the user and filled in by Howl.
...
sw_rendezvous_publish_id id;
if ((result = sw_rendezvous_publish(
session,
"HTTP",
"_http._tcp.",
NULL,
80,
"path=~scott",
NULL,
my_publish_reply,
NULL,
&id)) != SW_OKAY)
{
fprintf(stderr, "publish failed: %d\n", result);
return -1;
}
sw_rendezvous_run(session);
...
sw_rendezvous_stop_publish
, sw_rendezvous_run
, sw_rendezvous_publish_reply
sw_result
sw_rendezvous_stop_publish
(
sw_rendezvous session,
sw_rendezvous_publish_id id)
session
: The Rendezvous session.
id
: The id returned by sw_rendezvous_publish
.
if (sw_rendezvous_stop_publish(session, id) != SW_OKAY)
{
fprintf(stderr, "stop failed\n");
return -1;
}
SEE ALSO:
sw_result
sw_rendezvous_browse_domains
(
sw_rendezvous session,
sw_rendezvous_browse_handler handler,
sw_rendezvous_browse_reply
reply,
sw_opaque extra,
sw_rendezvous_browse_id *id)
sw_rendezvous_browse_domains
, the Howl system service calls your reply function once for each known domain on the Rendezvous network, and each time a new domain appears on the network.
To browse Rendezvous services rather than domains, see sw_rendezvous_browse_services
.
session
: The Rendezvous session.
handler
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. handler
is analogous to the C++ this
pointer, and is suitable for use as an object pointer when writing an object-oriented interface to Howl.
reply
: A pointer to the reply function.
extra
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. extra
is analogous to an argument passed to an object-oriented method call, in addition to the implicit "this
" argument supplied by handler
.
id
: Identifies the specific call to sw_rendezvous_browse_domains
, enabling other functions, like the reply function, to refer to the present request to browse. id
is allocated by the user and filled in by Howl.
sw_rendezvous_browse_id id;
if (sw_rendezvous_browse_domains(
session,
NULL,
my_browse_reply,
NULL,
&id) != SW_OKAY)
{
fprintf(stderr, "sw_rendezvous_browse_domains failed: %d\n", result);
return -1;
}
sw_rendezvous_run(session);
sw_rendezvous_stop_browse_domains
, sw_rendezvous_browse_services
, sw_rendezvous_browse_reply
sw_result
sw_rendezvous_stop_browse_domains
(
sw_rendezvous session,
sw_rendezvous_browse_id *id)
sw_rendezvous_browse_domains
.
session
: The Rendezvous session.
id
: The id returned by sw_rendezvous_browse_domains
.
if (sw_rendezvous_stop_browse_domains(session, id) != SW_OKAY)
{
fprintf(stderr, "stop failed\n");
return -1;
}
sw_rendezvous_browse_domains
sw_result
sw_rendezvous_browse_services
(
sw_rendezvous session,
sw_const_string type,
sw_const_string domain,
sw_rendezvous_browse_handler handler,
sw_rendezvous_browse_reply
reply,
sw_opaque extra,
sw_rendezvous_browse_id *id)
sw_rendezvous_browse_services
, the Howl system service calls your reply function once for each known service of the specified type on the Rendezvous network, and each time a new service appears on the network or an old service disappears.
session
: The Rendezvous session.
type
: The name of the type of the service, for example "_http._tcp.". UTF-8 encoded. See zeroconf.org and RFC2782 for details on the format of service type names. A NULL value is not allowed.
domain
: The domain that the service must be available from. UTF-8 encoded. Pass a NULL to allow services from any domain.
handler
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. handler
is analogous to the C++ this
pointer, and is suitable for use as an object pointer when writing an object-oriented interface to Howl.
reply
: A pointer to the reply function.
extra
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. extra
is analogous to an argument passed to an object-oriented method call, in addition to the implicit "this
" argument supplied by handler
.
id
: Identifies the specific call to sw_rendezvous_browse_services
, enabling other functions, like the reply function, to refer to the present request to browse. id
is allocated by the user and filled in by Howl.
sw_rendezvous_browse_id id;
if ((result = sw_rendezvous_browse_services(
session,
"_ftp._tcp.",
NULL,
NULL,
my_browse_reply,
NULL,
&id)) != SW_OKAY)
{
fprintf(stderr, "sw_rendezvous_browse_services failed: %d\n", result);
return -1;
}
sw_rendezvous_run
(session);
sw_rendezvous_stop_browse_services
sw_result
sw_rendezvous_stop_browse_services
(
sw_rendezvous session,
sw_rendezvous_browse_id *id)
sw_rendezvous_browse_services
.
session
: The Rendezvous session.
id
: The id returned by sw_rendezvous_browse_services
.
if (sw_rendezvous_stop_browse_services(session, id) != SW_OKAY)
{
fprintf(stderr, "stop failed\n");
return -1;
}
sw_rendezvous_browse_services
sw_result
sw_rendezvous_resolve
(
sw_rendezvous session,
sw_const_string name,
sw_const_string type,
sw_const_string domain,
sw_rendezvous_resolve_handler handler,
sw_rendezvous_resolve_reply
reply,
sw_opaque extra,
sw_rendezvous_resolve_id *id)
sw_rendezvous_resolve
and each time the port number or IP address changes.
session
: The Rendezvous session.
name
: The name of the service to resolve. UTF-8 encoded.
type
: The name of the type of the service, for example "_http._tcp.". UTF-8 encoded. See zeroconf.org and RFC2782 for details on the format of service type names. A NULL value is not allowed.
domain
: The domain that the service must be available from. UTF-8 encoded. Pass a NULL to allow services from any domain.
handler
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. handler
is analogous to the C++ this
pointer, and is suitable for use as an object pointer when writing an object-oriented interface to Howl.
reply
: A pointer to the reply function.
extra
: An arbitrary pointer, which Howl passes to the reply function. Howl never uses or dereferences this pointer. extra
is analogous to an argument passed to an object-oriented method call, in addition to the implicit "this
" argument supplied by handler
.
id
: Identifies the specific call to sw_rendezvous_resolve
, enabling other functions, like the reply function, to refer to the present request to resolve. id
is allocated by the user and filled in by Howl.
sw_rendezvous_browse_services
:
.
.
.
sw_result result;
sw_rendezvous_resolve_id rid;
switch (status)
{
.
.
.
case SW_RENDEZVOUS_BROWSE_ADD_SERVICE:
{
result = sw_rendezvous_resolve(
session,
name,
type,
domain,
NULL,
my_resolver,
NULL,
&rid);
}
break;
.
.
.
}
Note that there is no call to sw_rendezvous_run
, because sw_rendezvous_resolve
was called inside a reply function. Control of the CPU will return to Howl when the reply function returns.
sw_result
sw_rendezvous_stop_resolve
(
sw_rendezvous
sw_rendezvous_resolve_id)
sw_rendezvous_resolve
.
session
: The Rendezvous session.
id
: The id returned by sw_rendezvous_resolve
.
if (sw_rendezvous_stop_resolve(session, id) != SW_OKAY)
{
fprintf(stderr, "stop failed\n");
return -1;
}
sw_rendezvous_resolve
sw_result
sw_rendezvous_run
(sw_rendezvous session)
Once your program has called sw_rendezvous_run
, Howl calls reply functions. Before you've called sw_rendezvous_run
, Howl does not control the CPU and thus cannot call reply functions in response to asynchronous events like new Rendezvous services appearing.
int set_up_rendezvous_replies(void)
{
sw_rendezvous session;
if (sw_rendezvous_init(&session) != SW_OKAY)
{
fprintf(stderr, "init failed\n");
return -1;
}
.
. // set up reply functions here
.
sw_rendezvous_run(session);
}
typedef sw_result
(*sw_rendezvous_publish_reply
)(
sw_rendezvous_publish_handler handler,
sw_rendezvous rendezvous,
sw_rendezvous_publish_status
status,
sw_rendezvous_publish_id id,
sw_opaque extra);
sw_rendezvous_publish_reply
is the signature of the function called by the Howl system service to indicate the results of an attempt to publish. Howl is told to call this function through a call to sw_rendezvous_publish
.
handler
: The arbitrary pointer that was passed to sw_rendezvous_publish
.
rendezvous
: The Rendezvous session.
status
: The result of the attempt to publish.
id
: The id generated by sw_rendezvous_publish
, identifying the attempt to publish.
extra
: The arbitrary pointer that was passed to sw_rendezvous_publish
.
sw_rendezvous_publish_reply
should return the value SW_OKAY. The return value is included to allow future versions to return different values without breaking compatibility with old code.
sw_rendezvous_publish
typedef sw_result
(*sw_rendezvous_browse_reply
)(
sw_rendezvous_browse_handler handler,
sw_rendezvous rendezvous,
sw_rendezvous_browse_id id,
sw_rendezvous_browse_status
status,
sw_const_string name,
sw_const_string type,
sw_const_string domain,
sw_opaque extra);
sw_rendezvous_browse_reply
is the signature of the function called by the Howl system service to indicate that a Rendezvous domain or service has become available, is no longer available, or to communicate other status information. Howl is told to call this function through a call to sw_rendezvous_browse_domains
or sw_rendezvous_browse_services
.
When a sw_rendezvous_browse_reply
function is called to report on a service, the name
, type
, and domain
uniquely identify the service.
handler
: The arbitrary pointer that was passed to sw_rendezvous_browse_domains
or sw_rendezvous_browse_services
.
rendezvous
: The Rendezvous session.
id
: The id generated by sw_rendezvous_browse_domains
or sw_rendezvous_browse_services
, identifying the request to browse.
status
: Info about a domain or service, or status info about the request to browse.
name
: The name of the service being reported on by the Howl system service. Undefined for inappropriate values of status
. UTF-8 encoded.
type
: The type of the service being reported on by the Howl system service. UTF-8 encoded. Undefined for inappropriate values of status
.
domain
: The domain being reported on by the Howl system service. UTF-8 encoded. Undefined for inappropriate values of status
.
extra
: The arbitrary pointer that was passed to sw_rendezvous_browse_domains
or sw_rendezvous_browse_services
.
sw_rendezvous_browse_reply
should return the value SW_OKAY. The return value is included to allow future versions to return different values without breaking compatibility with old code.
sw_rendezvous_browse_domains
, sw_rendezvous_browse_services
typedef sw_result
(*sw_rendezvous_resolve_reply
)(
sw_rendezvous_resolve_handler handler,
sw_rendezvous rendezvous,
sw_rendezvous_resolve_id id,
sw_const_string name,
sw_const_string type,
sw_const_string domain,
sw_address address,
sw_port port,
sw_const_string textRecord,
sw_opaque extra);
sw_rendezvous_resolve_reply
is the signature of the function called by the Howl system service to communicate the port number and IP address of the socket providing a service. Howl is told to call this function through a call to sw_rendezvous_resolve
.
handler
: The arbitrary pointer that was passed to sw_rendezvous_resolve
.
rendezvous
: The Rendezvous session.
id
: The id generated by sw_rendezvous_resolve
, identifying the request to browse.
name
: The name of the service being reported on by the Howl system service. UTF-8 encoded.
type
: The type of the service being reported on by the Howl system service. UTF-8 encoded.
domain
: The domain being reported on by the Howl system service. UTF-8 encoded.
address
: The IP address of the service.
port
: The port number of the socket where the service is available.
textRecord
: An arbitrary text string describing the service.
extra
: The arbitrary pointer that was passed to sw_rendezvous_resolve
.
sw_rendezvous_resolve_reply
should return the value SW_OKAY. The return value is included to allow future versions to return different values without breaking compatibility with old code.
sw_rendezvous_resolve
, sw_address
typedef enum sw_rendezvous_publish_status
{
SW_RENDEZVOUS_PUBLISH_STARTED,
SW_RENDEZVOUS_PUBLISH_STOPPED,
SW_RENDEZVOUS_PUBLISH_NAME_COLLISION,
SW_RENDEZVOUS_PUBLISH_INVALID
} sw_rendezvous_publish_status
;
sw_rendezvous_publish_reply
function.
SW_RENDEZVOUS_PUBLISH_STARTED
: publishing of the specified service has started successfully.
SW_RENDEZVOUS_PUBLISH_STOPPED
: the specified service is now no longer published.
SW_RENDEZVOUS_PUBLISH_NAME_COLLISION
: the specified service could not be published because it has the same name as another service already on the Rendezvous network.
SW_RENDEZVOUS_PUBLISH_INVALID
: a general catch-all error code.
Future versions of Howl may add more values.
sw_rendezvous_publish_reply
typedef enum sw_rendezvous_browse_status
{
SW_RENDEZVOUS_BROWSE_INVALID,
SW_RENDEZVOUS_BROWSE_RELEASE,
SW_RENDEZVOUS_BROWSE_ADD_DOMAIN,
SW_RENDEZVOUS_BROWSE_ADD_DEFAULT_DOMAIN,
SW_RENDEZVOUS_BROWSE_REMOVE_DOMAIN,
SW_RENDEZVOUS_BROWSE_ADD_SERVICE,
SW_RENDEZVOUS_BROWSE_REMOVE_SERVICE
} sw_rendezvous_browse_status
;
sw_rendezvous_browse_reply
function.
SW_RENDEZVOUS_BROWSE_INVALID
: a general catch-all error code.
SW_RENDEZVOUS_BROWSE_RELEASE
: browsing has been stopped, as requested by call to sw_rendezvous_stop_browse_domains
or sw_rendezvous_stop_browse_services
.
SW_RENDEZVOUS_BROWSE_ADD_DOMAIN
: the specified domain is now accessible on the Rendezvous network.
SW_RENDEZVOUS_BROWSE_ADD_DEFAULT_DOMAIN
: the default Rendezvous domain, "local.", has been established.
SW_RENDEZVOUS_BROWSE_REMOVE_DOMAIN
: the specified domain has been removed from the Rendezvous network.
SW_RENDEZVOUS_BROWSE_ADD_SERVICE
: the specified service is now available on the Rendezvous network.
SW_RENDEZVOUS_BROWSE_REMOVE_SERVICE
: the specified service has been removed from the Rendezvous network.
Future versions of Howl may add more values.
sw_rendezvous_publish_reply
typedef sw_long sw_result
;
Possible values:
SW_OKAY
: the call succeeded.
SW_RENDEZVOUS_E_NO_MEM
: failed: out of memory.
SW_RENDEZVOUS_E_BAD_PARAM
: the function was passed an invalid argument, like attempting to publish a service with an invalid name.
SW_RENDEZVOUS_E_UNKNOWN
: a general catchall error code.
Future versions of Howl may add more values.