@need 3200

@node A VU Handler for the URL Socket Scheme
@chapter A VU Handler for the URL Socket Scheme

These functions provide VU namespace handlers for file-names
that designate various kinds of sockets.  By using these handlers,
your programs can (almost) transparently handle filenames
like:

@example
@group
     inet://myserver.host.com:10000
@end group
@group
@end group
@end example

@noindent
or

@example
@group
     unix:/tmp/.X11-unix/X0
@end group
@group
@end group
@end example

Two kinds of sockets are available: @emph{server} sockets and @emph{client}
sockets.


@geindex server sockets
@dfn{server sockets} are created with @code{socket(2)}, @code{bind(2)}, and
@code{listen(2)}.  When @code{vu_open} is called, a call to @code{listen(2)} is
made and the client connection (if any) is returned.


@geindex client sockets
@dfn{client sockets} are created with @code{socket(2)}, @code{bind(2)}, and
@code{connect(2)}.


Sockets may be named in either the @code{unix} or @code{inet} domains.


The syntax of these URLs is described in the documentation for
@code{url_socket_push_client_handler} and
@code{url_socket_push_socket_handler}.

@sp 1
@need 1750
@noindent
@b{* Function} @code{url_socket_push_client_handler}@fuindex url_socket_push_client_handler
@*
@example
@group
void url_socket_push_client_handler (enum url_socket_domains domains,
                                     int default_port,
                                     int is_optional);
@end group
@group
@end group
@end example

Push a VU namespace handler for client sockets.

@example
@group
     Domains:                        File Name:
     ------------------------------------------------------------------
     url_socket_unix                 unix:$PATH
     url_socket_inet                 inet://$HOST[:$PORT]
     url_socket_inet_or_unix         unix:$PATH or inet://$HOST[:$PORT]
@end group
@group
@end group
@end example

Note that the @code{$PATH} of a unix domain socket is subject to @geindex ~
@dfn{~} expansion
using @code{file_name_tilde_expand}.


(See @strong{file_name_tilde_expand} in @ref{Home Directories}.)


@code{default_port} is used for internet-domain sockets.


If @code{is_optional} is @code{0}, the handler is immediately added to the VU namespace.
If @code{is_optional} is not @code{0}, the handler is added to the list of optional
handlers and may be enabled by @code{vu_enable_optional_name_handler}.


(See @strong{vu_enable_optional_name_handler} in @ref{Establishing VU Handlers}.)

@example
@group
     Domains:                        Optional Handler Name:
     ------------------------------------------------------------------
     url_socket_unix                 client/unix
     url_socket_inet                 client/inet
     url_socket_inet_or_unix         client/any
@end group
@group
@end group
@end example
@sp 1
@need 1750
@noindent
@b{* Function} @code{url_socket_push_socket_handler}@fuindex url_socket_push_socket_handler
@*
@example
@group
void url_socket_push_socket_handler 
     (enum url_socket_domains domains,
      int server_flags,
      int may_be_client,
      int only_server_url,
@end group
@group
      int default_port,
      int backlog,
@end group
@group
      url_socket_server_callback server_callback,
      url_socket_connect_callback connection_callback,
      url_socket_server_close_callback server_close_callback,
      void * closure,
      is_optional);
@end group
@group
@end group
@end example

Push a VU namespace handler for server sockets.  After this call, a
call to @code{vu_open} with a suitable file name will work by creating a
socket.


@code{server_flags} may be any bitwise combination of:

@example
@group
             O_NONBLOCK      # Don't block waiting for connections.
@end group
@group
@end group
@end example

There are two kinds of file name patterns: those that can be used
to name both clients and servers, and those that can only be used
to name servers:

@example
@group
     server only:                    client or server:
     -------------------------------------------------
     unix-server:$PATH               unix:$PATH
     inet-server://$HOST[:$PORT]     inet://$HOST[:$PORT]
@end group
@group
@end group
@end example

By default, both kinds of URL are accepted and interpreted as names
of server sockets.  Note that:

@example
@group
     `$PATH' of a unix domain socket is  subject to "~" expansion using 
     `file_name_tilde_expand'.
@end group
@group
@end group
@end example
@example
@group
     `$HOST' of an internet-domain socket may be `INADDR_LOOPBACK'.
     If the URL is the name of a server, `$HOST' may also be
     `INADDR_ANY'.  (See `inet(4)'.)
@end group
@group
@end group
@end example
@example
@group
     `$PORT' of an internet-domain server may be 0, meaning that the
     system should assign a port number which will be reported in 
     the server callback in the `server_addr' parameter (see below).
@end group
@group
@end group
@end example

If @code{may_be_client} is not @code{0}, then accept both kinds of URLs, but
interpret @geindex client or server
@dfn{client or server} URLs as naming client sockets (your
process will open a connection to some other server).


If @code{only_server_url} is not @code{0}, then accept @geindex server only
@dfn{server only} URLs, but
not @geindex client or server
@dfn{client or server} URLs.  In this case, @code{may_be_client} is
ignored.  This is especially useful in combination with
@code{url_socket_push_client_handler} and other calls to
@code{vu_push_name_handler}.


@code{default_port} is used when creating an internet-domain socket for
which the port number was not specified in the file-name.


@code{backlog} is used for the call to @code{listen(2)}.


@code{server_callback} is called when a new server socket has been
created successfully.  It's arguments are explained below.


@code{connect_callback} is called when a new connection has been
received.  It's arguments are explained below.


@code{server_close_callback} is called when the server descriptor
is closed.  It's arguments are explained below.


@code{closure} is an opaque value passed to the callback functions.


If @code{is_optional} is @code{0}, the handler is immediately added to the VU namespace.
If @code{is_optional} is non-0, the handler is added to the list of optional
handlers and may be enabled by @code{vu_enable_optional_name_handler}.

@example
@group
  domain(s) only_server_url may_be_client         Optional Handler Name
  --------------------------------------------------------------------
  unix            0               0               server/unix
  inet            0               0               server/inet
  inet_or_unix    0               0               server/any
@end group
@group
  unix            0               1               socket/unix
@end group
@group
  inet            0               1               socket/inet
  inet_or_unix    0               1               socket/any
  unix            1               *               socket/unix-server
  inet            1               *               socket/inet-server
  inet_or_unix    1               *               socket/any-server
@end group
@group
@end group
@end example

@strong{Calling Conventions for Callbacks}

@example
@group
 typedef void (*url_socket_server_callback) (char * path,
                                             int server_flags,
                                             int flags,
                                             int mode,
                                             int server_fd,
                                             struct sockaddr * server_addr,
                                             int server_addr_len,
                                             void * closure);
@end group
@group
@end group
@end example
@example
@group
     `path' is the file name that caused the server socket to
     be created.
@end group
@group
@end group
@end example
@example
@group
     `server_flags' is 0 or a bit-wise combination of `O_NONBLOCK'.
@end group
@group
@end group
@end example
@example
@group
     `flags' is the `flags' parameter passed to `vu_open', if this
     server socket was created by a call to `vu_open', 0 otherwise.
@end group
@group
@end group
@end example
@example
@group
     `mode' is the `mode' parameter passed to `vu_open', if this
     server socket was created by a call to `vu_open', 0 otherwise.
@end group
@group
@end group
@end example
@example
@group
     `server_fd' is the descriptor number of the server socket.
@end group
@group
@end group
@end example
@example
@group
     `server_addr' and `server_addr_len' is the address passed to
     `bind'.
@end group
@group
@end group
@end example
@example
@group
     `closure' is the `closure' argument passed to
     `url_socket_push_socket_handler'.
@end group
@group
@end group
@end example
@example
@group
 typedef void (*url_socket_connect_callback) 
             (char * path,
              int flags,
              int mode,
              int server_fd,
              int connection_fd,
              struct sockaddr * client_addr,
              int client_addr_len,
              void * closure);
@end group
@group
@end group
@end example
@example
@group
     `path' is the file name that caused the client connection to this
     server to be created.
@end group
@group
@end group
@end example
@example
@group
     `flags' is the `flags' parameter passed to `vu_open'.
@end group
@group
@end group
@end example
@example
@group
     `mode' is the `mode' parameter passed to `vu_open'.
@end group
@group
@end group
@end example
@example
@group
     `server_fd' is the descriptor number of the server socket.
@end group
@group
@end group
@end example
@example
@group
     `connection_fd' is the descriptor number of the client connection.
@end group
@group
@end group
@end example
@example
@group
     `client_addr' and `client_addr_len' is the address from `accept'.
@end group
@group
@end group
@end example
@example
@group
     `closure' is the `closure' argument passed to
     `url_socket_push_socket_handler'.
@end group
@group
@end group
@end example
@example
@group
 typedef void (*url_socket_server_close_callback) 
             (int server_fd,
              struct sockaddr * server_addr,
              int server_addr_len,
              void * closure);
@end group
@group
@end group
@end example
@example
@group
     `server_fd' is the descriptor number of the server socket.
@end group
@group
@end group
@end example
@example
@group
     `server_addr' and `server_addr_len' is the address passed to
     `bind'.
@end group
@group
@end group
@end example
@example
@group
     `closure' is the `closure' argument passed to
     `url_socket_push_socket_handler'.
@end group
@group
@end group
@end example



