Re: Socket API improvement, patch #6

[ludovic.courtes@laas.fr (Ludovic Courtès)]

Hi,

Kevin Ryde <user42@zip.com.au> writes:

> Ok, we got there eventually.  I checked it in, and I updated the docs
> (have a read to see it they look right).

Great, thanks!

The doc looks good to me.  I'd just suggest the following patch.  It
documents the wrapping/unwrapping C functions (since that was my
original goal).

Thanks,
Ludovic.


--- orig/doc/ref/posix.texi
+++ mod/doc/ref/posix.texi
@@ -2449,18 +2449,20 @@
 @subsubsection Network Socket Address
 @cindex socket
 @cindex network socket
+@cindex socket address
 
-A socket address object identifies a socket endpoint for
-communication.  In the case of @code{AF_INET} for instance, the host
-address is only the machine (or interface on the machine), a port
-number is also needed to specify a particular open socket in a running
+A @dfn{socket address} object identifies a socket endpoint for
+communication.  In the case of @code{AF_INET} for instance, the socket
+address object comprises the machine (or interface on the machine) and
+a port number needed to specify a particular open socket in a running
 client or server process.
 
 A socket address object can be created with,
 
-@defun {Scheme Procedure} make-socket-address AF_INET ipv4addr port
-@defunx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
-@defunx {Scheme Procedure} make-socket-address AF_UNIX path
+@deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
+@deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
+@deffnx {Scheme Procedure} make-socket-address AF_UNIX path
+@deffnx {C Function} scm_make_socket_address family address args
 Return a new socket address object.  The first argument is the address
 family, one of the @code{AF} constants, then the arguments vary
 according to the family.
@@ -2473,7 +2475,7 @@
 arguments may be given (both integers, default 0).
 
 For @code{AF_UNIX} the argument is a filename (a string).
-@end defun
+@end deffn
 
 @noindent
 The following functions access the fields of a socket address object,
@@ -2508,6 +2510,34 @@
 scope ID value.
 @end deffn
 
+Guile also defines C functions to manipulate socket address objects
+and to convert them from/to their C representation (a @code{struct
+sockaddr} object) to/from their Scheme representation.
+
+@deftypefn {C Function} {struct sockaddr *}scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *address_size)
+Return a newly-allocated @code{sockaddr} structure that reflects
+@var{address}, an address of family @var{family}, with the
+family-specific parameters @var{args} (see the description of
+@var{make-socket-address} for details).  On success, a non-@code{NULL}
+pointer is returned and @var{address_size} is updated to the actual
+size (in bytes) of the returned address.  The returned structure must
+eventually be freed using @code{free ()}.
+@end deftypefn
+
+@deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size)
+Return the Scheme object representing @var{address}, a C socket
+address object of size @var{address_size} bytes.
+@end deftypefn
+
+@deftypefn {C Function} {struct sockaddr *}scm_to_sockaddr (SCM address, size_t *address_size)
+Return a newly-allocated @code{sockaddr} structure that reflects
+@var{address}, an address object returned by either
+@code{scm_from_sockaddr ()} or @code{scm_make_socket_address ()}, into
+its C representation.  On success, a non-@code{NULL} pointer is
+returned and @var{address_size} is updated to the actual size (in
+bytes) of the returned address.  The returned value must eventually be
+freed using @code{free ()}.
+@end deftypefn
 
 @node Network Sockets and Communication
 @subsubsection Network Sockets and Communication



_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user