sw_rendezvous

OVERVIEW

The sw_rendezvous functions manage a session of interaction with the Rendezvous network. Each of these functions performs an IPC call to a system service.

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.


FUNCTION

sw_rendezvous_init

SYNOPSIS

sw_result
sw_rendezvous_init(
   sw_rendezvous *session)

DESCRIPTION

Creates a new 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.

EXAMPLE

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

SEE ALSO

sw_rendezvous_fina, sw_rendezvous_run, sw_rendezvous_init_with_salt


FUNCTION

sw_rendezvous_init_with_salt

SYNOPSIS

sw_result
sw_rendezvous_init_with_salt(
   sw_rendezvous *session,
   sw_salt        salt)

DESCRIPTION

Creates a new Rendezvous session. 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.

EXAMPLE

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

SEE ALSO

sw_rendezvous_fina, sw_rendezvous_run, sw_rendezvous_init_with_salt


FUNCTION

sw_rendezvous_fina

SYNOPSIS

sw_result
sw_rendezvous_fina(
   sw_rendezvous session)

DESCRIPTION

Closes a Rendezvous session. Deallocates all resources associated with the session: memory, sockets, everything else.

EXAMPLE

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);
   ...
}

SEE ALSO

sw_rendezvous_init, sw_rendezvous_init_with_salt


FUNCTION

sw_rendezvous_publish

SYNOPSIS

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)

DESCRIPTION

Publishes a Rendezvous service. After calling 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.

EXAMPLE

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

SEE ALSO

sw_rendezvous_stop_publish, sw_rendezvous_run, sw_rendezvous_publish_reply


FUNCTION

sw_rendezvous_stop_publish

SYNOPSIS

sw_result
sw_rendezvous_stop_publish(
   sw_rendezvous             session,
   sw_rendezvous_publish_id  id)

DESCRIPTION

Stops publication of a Rendezvous service.

session: The Rendezvous session.

id: The id returned by sw_rendezvous_publish.

EXAMPLE

if (sw_rendezvous_stop_publish(session, id) != SW_OKAY)
{
   fprintf(stderr, "stop failed\n");
   return -1;
}

SEE ALSO:

sw_rendezvous_publish


FUNCTION

sw_rendezvous_browse_domains

SYNOPSIS

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)

DESCRIPTION

Causes Howl to notify your program of the existence of every accessible Rendezvous domain. After calling 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.

EXAMPLE

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

SEE ALSO

sw_rendezvous_stop_browse_domains, sw_rendezvous_browse_services, sw_rendezvous_browse_reply


FUNCTION

sw_rendezvous_stop_browse_domains

SYNOPSIS

sw_result
sw_rendezvous_stop_browse_domains(
   sw_rendezvous            session,
   sw_rendezvous_browse_id *id)

DESCRIPTION

Stops calls to the reply function set up by a previous call to sw_rendezvous_browse_domains.

session: The Rendezvous session.

id: The id returned by sw_rendezvous_browse_domains.

EXAMPLE

if (sw_rendezvous_stop_browse_domains(session, id) != SW_OKAY)
{
   fprintf(stderr, "stop failed\n");
   return -1;
}

SEE ALSO

sw_rendezvous_browse_domains


FUNCTION

sw_rendezvous_browse_services

SYNOPSIS

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)

DESCRIPTION

Causes Howl to notify your program of the existence every Rendezvous service of a specified type. After calling 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.

EXAMPLE

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

SEE ALSO

sw_rendezvous_stop_browse_services


FUNCTION

sw_rendezvous_stop_browse_services

SYNOPSIS

sw_result
sw_rendezvous_stop_browse_services(
   sw_rendezvous            session,
   sw_rendezvous_browse_id *id)

DESCRIPTION

Stops calls to the reply function set up by a previous call to sw_rendezvous_browse_services.

session: The Rendezvous session.

id: The id returned by sw_rendezvous_browse_services.

EXAMPLE

if (sw_rendezvous_stop_browse_services(session, id) != SW_OKAY)
{
   fprintf(stderr, "stop failed\n");
   return -1;
}

SEE ALSO

sw_rendezvous_browse_services


FUNCTION

sw_rendezvous_resolve

SYNOPSIS

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)

DESCRIPTION

Causes Howl to notify your program of the port number and IP address of a specified service, as established at the time of the call to 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.

EXAMPLE

Inside a reply function for 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.


FUNCTION

sw_rendezvous_stop_resolve

SYNOPSIS

sw_result
sw_rendezvous_stop_resolve(
   sw_rendezvous
   sw_rendezvous_resolve_id)

DESCRIPTION

Stops calls to the reply function set up by a previous call to sw_rendezvous_resolve.

session: The Rendezvous session.

id: The id returned by sw_rendezvous_resolve.

EXAMPLE

if (sw_rendezvous_stop_resolve(session, id) != SW_OKAY)
{
   fprintf(stderr, "stop failed\n");
   return -1;
}

SEE ALSO

sw_rendezvous_resolve


FUNCTION

sw_rendezvous_run

SYNOPSIS

sw_result
sw_rendezvous_run(sw_rendezvous session)

DESCRIPTION

Yields control of the CPU to Howl. Does not return.

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.

EXAMPLE

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


CALLBACK

sw_rendezvous_publish_reply

SYNOPSIS

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

DESCRIPTION

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.

RETURN VALUE

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.

SEE ALSO

sw_rendezvous_publish


CALLBACK

sw_rendezvous_browse_reply

SYNOPSIS

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

DESCRIPTION

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.

RETURN VALUE

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.

SEE ALSO

sw_rendezvous_browse_domains, sw_rendezvous_browse_services


CALLBACK

sw_rendezvous_resolve_reply

SYNOPSIS

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

DESCRIPTION

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.

RETURN VALUE

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.

SEE ALSO

sw_rendezvous_resolve, sw_address


ENUM

sw_rendezvous_publish_status

SYNOPSIS

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;

DESCRIPTION

Status codes that can be sent to a 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.

SEE ALSO

sw_rendezvous_publish_reply


ENUM

sw_rendezvous_browse_status

SYNOPSIS

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;

DESCRIPTION

Status codes that can be sent to a 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.

SEE ALSO

sw_rendezvous_publish_reply


DATA TYPE

sw_result

SYNOPSIS

typedef sw_long sw_result;

DESCRIPTION

The return code of a call to any Howl subroutine.

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.