Added: harmony/standard/site/docs/externals/vm_doc/html/hysock_8c.html URL: http://svn.apache.org/viewvc/harmony/standard/site/docs/externals/vm_doc/html/hysock_8c.html?rev=724734&view=auto ============================================================================== --- harmony/standard/site/docs/externals/vm_doc/html/hysock_8c.html (added) +++ harmony/standard/site/docs/externals/vm_doc/html/hysock_8c.html Tue Dec 9 07:03:45 2008 @@ -0,0 +1,4023 @@ + + +Harmony Class Library Porting: modules/portlib/src/main/native/port/windows/hysock.c File Reference + + + + +
+ +
+

modules/portlib/src/main/native/port/windows/hysock.c File Reference


Detailed Description

+Sockets. +

+ +

+#include "hysock.h"
+#include "portpriv.h"
+#include "hyportptb.h"
+#include <Iphlpapi.h>
+#include <limits.h>
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Functions

I_32 VMCALL hysock_accept (struct HyPortLibrary *portLibrary, hysocket_t serverSock, hysockaddr_t addrHandle, hysocket_t *sockHandle)
 The accept function extracts the first connection on the queue of pending connections on socket sock.
I_32 VMCALL hysock_bind (struct HyPortLibrary *portLibrary, hysocket_t sock, hysockaddr_t addr)
 The bind function is used on an unconnected socket before subsequent calls to the connect or listen functions.
I_32 VMCALL hysock_close (struct HyPortLibrary *portLibrary, hysocket_t *sock)
 The close function closes a socket.
I_32 VMCALL hysock_connect (struct HyPortLibrary *portLibrary, hysocket_t sock, hysockaddr_t addr)
 Establish a connection to a peer.
const char *VMCALL hysock_error_message (struct HyPortLibrary *portLibrary)
 Return an error message describing the last OS error that occurred.
I_32 VMCALL hysock_fdset_init (struct HyPortLibrary *portLibrary, hysocket_t socketP)
 Create a file descriptor (FD) set of one element.
I_32 VMCALL hysock_fdset_size (struct HyPortLibrary *portLibrary, hysocket_t handle)
 Answer the maximum size of the fdset currently declared for the platform.
I_32 VMCALL hysock_freeaddrinfo (struct HyPortLibrary *portLibrary, hyaddrinfo_t handle)
 Frees the memory created by the call to hysock_getaddrinfo().
I_32 VMCALL hysock_getaddrinfo (struct HyPortLibrary *portLibrary, char *name, hyaddrinfo_t hints, hyaddrinfo_t result)
 Answers a list of addresses as an opaque pointer in "result".
I_32 VMCALL hysock_getaddrinfo_address (struct HyPortLibrary *portLibrary, hyaddrinfo_t handle, U_8 *address, int index, U_32 *scope_id)
 Answers a U_8 array representing the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0.
I_32 VMCALL hysock_getaddrinfo_create_hints (struct HyPortLibrary *portLibrary, hyaddrinfo_t *result, I_16 family, I_32 socktype, I_32 protocol, I_32 flags)
 Answers a hints structure as an opaque pointer in "result".
I_32 VMCALL hysock_getaddrinfo_family (struct HyPortLibrary *portLibrary, hyaddrinfo_t handle, I_32 *family, int index)
 Answers the family type of the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0.
I_32 VMCALL hysock_getaddrinfo_length (struct HyPortLibrary *portLibrary, hyaddrinfo_t handle, I_32 *length)
 Answers the number of results returned from hysock_getaddrinfo.
I_32 VMCALL hysock_getaddrinfo_name (struct HyPortLibrary *portLibrary, hyaddrinfo_t handle, char *name, int index)
 Answers the cannon name of the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0.
I_32 VMCALL hysock_gethostbyaddr (struct HyPortLibrary *portLibrary, char *addr, I_32 length, I_32 type, hyhostent_t handle)
 Answer information on the host referred to by the address.
I_32 VMCALL hysock_gethostbyname (struct HyPortLibrary *portLibrary, char *name, hyhostent_t handle)
 Answer information on the host, specified by name.
I_32 VMCALL hysock_gethostname (struct HyPortLibrary *portLibrary, char *buffer, I_32 length)
 Answer the name of the local host machine.
I_32 VMCALL hysock_getnameinfo (struct HyPortLibrary *portLibrary, hysockaddr_t in_addr, I_32 sockaddr_size, char *name, I_32 name_length, int flags)
 Answers the host name of the "in_addr" in a preallocated buffer.
I_32 VMCALL hysock_getopt_bool (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, BOOLEAN *optval)
 Answer the value of the nominated boolean socket option.
I_32 VMCALL hysock_getopt_byte (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, U_8 *optval)
 Answer the value of the nominated byte socket option.
I_32 VMCALL hysock_getopt_int (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, I_32 *optval)
 Answer the value of the nominated integer socket option.
I_32 VMCALL hysock_getopt_linger (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hylinger_t optval)
 Answer the value of the socket linger option.
I_32 VMCALL hysock_getopt_sockaddr (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hysockaddr_t optval)
 Answer the value of the socket option, an address struct.
I_32 VMCALL hysock_getpeername (struct HyPortLibrary *portLibrary, hysocket_t handle, hysockaddr_t addrHandle)
 Answer the remote name for the socket.
I_32 VMCALL hysock_getsockname (struct HyPortLibrary *portLibrary, hysocket_t handle, hysockaddr_t addrHandle)
 Answer the local name for the socket.
I_32 VMCALL hysock_hostent_addrlist (struct HyPortLibrary *portLibrary, hyhostent_t handle, U_32 index)
 Answer the nominated element of the address list within the argument hostent struct.
I_32 VMCALL hysock_hostent_aliaslist (struct HyPortLibrary *portLibrary, hyhostent_t handle, char ***aliasList)
 Answer a reference to the list of alternative names for the host within the argument hostent struct.
I_32 VMCALL hysock_hostent_hostname (struct HyPortLibrary *portLibrary, hyhostent_t handle, char **hostName)
 Answer the host name (string) within the argument hostent struct.
I_32 VMCALL hysock_htonl (struct HyPortLibrary *portLibrary, I_32 val)
 Answer the 32 bit host ordered argument, in network byte order.
U_16 VMCALL hysock_htons (struct HyPortLibrary *portLibrary, U_16 val)
 Answer the 16 bit host ordered argument, in network byte order.
I_32 VMCALL hysock_inetaddr (struct HyPortLibrary *portLibrary, char *addrStr, U_32 *addr)
 Answer the dotted IP string as an Internet address.
I_32 VMCALL hysock_inetntoa (struct HyPortLibrary *portLibrary, char **addrStr, U_32 nipAddr)
 Answer the Internet address as a dotted IP string.
I_32 VMCALL hysock_ipmreq_init (struct HyPortLibrary *portLibrary, hyipmreq_t handle, U_32 nipmcast, U_32 nipinterface)
 Initializes a new multicast membership structure.
I_32 VMCALL hysock_ipv6_mreq_init (struct HyPortLibrary *portLibrary, hyipv6_mreq_t handle, U_8 *ipmcast_addr, U_32 ipv6mr_interface)
 Fills in a preallocated hyipv6_mreq_struct.
I_32 VMCALL hysock_linger_enabled (struct HyPortLibrary *portLibrary, hylinger_t handle, BOOLEAN *enabled)
 Answer true if the linger is enabled in the argument linger struct.
I_32 VMCALL hysock_linger_init (struct HyPortLibrary *portLibrary, hylinger_t handle, I_32 enabled, U_16 timeout)
 Initializes a new linger structure, enabled or disabled, with the timeout as specified.
I_32 VMCALL hysock_linger_linger (struct HyPortLibrary *portLibrary, hylinger_t handle, U_16 *linger)
 Answer the linger timeout value in the argument linger struct.
I_32 VMCALL hysock_listen (struct HyPortLibrary *portLibrary, hysocket_t sock, I_32 backlog)
 Set the socket to listen for incoming connection requests.
I_32 VMCALL hysock_ntohl (struct HyPortLibrary *portLibrary, I_32 val)
 Answer the 32 bit network ordered argument, in host byte order.
U_16 VMCALL hysock_ntohs (struct HyPortLibrary *portLibrary, U_16 val)
 Answer the 16-bit network ordered argument, in host byte order.
I_32 VMCALL hysock_read (struct HyPortLibrary *portLibrary, hysocket_t sock, U_8 *buf, I_32 nbyte, I_32 flags)
 The read function receives data from a connected socket.
I_32 VMCALL hysock_readfrom (struct HyPortLibrary *portLibrary, hysocket_t sock, U_8 *buf, I_32 nbyte, I_32 flags, hysockaddr_t addrHandle)
 The read function receives data from a possibly connected socket.
I_32 VMCALL hysock_select (struct HyPortLibrary *portLibrary, I_32 nfds, hyfdset_t readfds, hyfdset_t writefds, hyfdset_t exceptfds, hytimeval_t timeout)
 The select function allows the state of sockets for read & write operations and exceptional conditions to be tested.
I_32 VMCALL hysock_select_read (struct HyPortLibrary *portLibrary, hysocket_t hysocketP, I_32 secTime, I_32 uSecTime, BOOLEAN accept)
 A helper method, to ensure a read operation can be performed without blocking.
I_32 VMCALL hysock_set_nonblocking (struct HyPortLibrary *portLibrary, hysocket_t socketP, BOOLEAN nonblocking)
 Set the nonblocking state of the socket.
I_32 VMCALL hysock_setflag (struct HyPortLibrary *portLibrary, I_32 flag, I_32 *arg)
 Ensure the flag designated is set in the argument.
I_32 VMCALL hysock_setopt_bool (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, BOOLEAN *optval)
 Set the value of the nominated boolean socket option.
I_32 VMCALL hysock_setopt_byte (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, U_8 *optval)
 Set the value of the nominated byte socket option.
I_32 VMCALL hysock_setopt_int (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, I_32 *optval)
 Set the value of the nominated integer socket option.
I_32 VMCALL hysock_setopt_ipmreq (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hyipmreq_t optval)
 Set the multicast request on this socket.
I_32 VMCALL hysock_setopt_ipv6_mreq (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hyipv6_mreq_t optval)
 Set the multicast request on this socket for IPv6 sockets.
I_32 VMCALL hysock_setopt_linger (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hylinger_t optval)
 Set the linger value on the socket.
I_32 VMCALL hysock_setopt_sockaddr (struct HyPortLibrary *portLibrary, hysocket_t socketP, I_32 optlevel, I_32 optname, hysockaddr_t optval)
 Set the sockaddr for the socket.
I_32 VMCALL hysock_shutdown (struct HyPortLibrary *portLibrary)
 Terminates use of the socket library.
I_32 VMCALL hysock_shutdown_input (struct HyPortLibrary *portLibrary, hysocket_t sock)
 The shutdown_input function disables the input stream on a socket.
I_32 VMCALL hysock_shutdown_output (struct HyPortLibrary *portLibrary, hysocket_t sock)
 The shutdown_output function disables the output stream on a socket.
I_32 VMCALL hysock_sockaddr (struct HyPortLibrary *portLibrary, hysockaddr_t handle, char *addrStr, U_16 port)
 Creates a new hysockaddr, refering to the specified port and address.
I_32 VMCALL hysock_sockaddr_address (struct HyPortLibrary *portLibrary, hysockaddr_t handle)
 Answer the address, in network order, of the hysockaddr argument.
I_32 VMCALL hysock_sockaddr_address6 (struct HyPortLibrary *portLibrary, hysockaddr_t handle, U_8 *address, U_32 *length, U_32 *scope_id)
 Answers the IP address of a structure and its length, in a preallocated buffer.
I_32 VMCALL hysock_sockaddr_family (struct HyPortLibrary *portLibrary, I_16 *family, hysockaddr_t handle)
 Answers the family name of a hysockaddr_struct.
I_32 VMCALL hysock_sockaddr_init (struct HyPortLibrary *portLibrary, hysockaddr_t handle, I_16 family, U_32 nipAddr, U_16 nPort)
 Creates a new hysockaddr, refering to the specified port and address.
I_32 VMCALL hysock_sockaddr_init6 (struct HyPortLibrary *portLibrary, hysockaddr_t handle, U_8 *addr, I_32 addrlength, I_16 family, U_16 nPort, U_32 flowinfo, U_32 scope_id, hysocket_t sock)
 Answers an initialized hysockaddr_struct structure.
U_16 VMCALL hysock_sockaddr_port (struct HyPortLibrary *portLibrary, hysockaddr_t handle)
 Answer the port, in network order, of the hysockaddr argument.
I_32 VMCALL hysock_socket (struct HyPortLibrary *portLibrary, hysocket_t *handle, I_32 family, I_32 socktype, I_32 protocol)
 Creates a new socket descriptor and any related resources.
I_32 VMCALL hysock_socketIsValid (struct HyPortLibrary *portLibrary, hysocket_t handle)
 Determines whether or not the socket is valid.
I_32 VMCALL hysock_startup (struct HyPortLibrary *portLibrary)
 Initiate the use of sockets by a process.
I_32 VMCALL hysock_timeval_init (struct HyPortLibrary *portLibrary, U_32 secTime, U_32 uSecTime, hytimeval_t timeP)
 Create a time structure, representing the timeout period defined in seconds & microSeconds.
I_32 VMCALL hysock_write (struct HyPortLibrary *portLibrary, hysocket_t sock, U_8 *buf, I_32 nbyte, I_32 flags)
 The write function writes data to a connected socket.
I_32 VMCALL hysock_writeto (struct HyPortLibrary *portLibrary, hysocket_t sock, U_8 *buf, I_32 nbyte, I_32 flags, hysockaddr_t addrHandle)
 The writeto function writes data to a datagram socket.
I_32 VMCALL hysock_get_network_interfaces (struct HyPortLibrary *portLibrary, struct hyNetworkInterfaceArray_struct *array, BOOLEAN preferIPv4Stack)
 Queries and returns the information for the network interfaces that are currently active within the system.
I_32 VMCALL hysock_free_network_interface_struct (struct HyPortLibrary *portLibrary, struct hyNetworkInterfaceArray_struct *array)
 Frees the memory allocated for the hyNetworkInterface_struct array passed in.
I_32 VMCALL hysock_connect_with_timeout (struct HyPortLibrary *portLibrary, hysocket_t sock, hysockaddr_t addr, U_32 timeout, U_32 step, U_8 **context)
 Establish a connection to a peer with a timeout.
+


Function Documentation

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_accept (struct HyPortLibrary portLibrary,
hysocket_t  serverSock,
hysockaddr_t  addrHandle,
hysocket_t *  sockHandle 
)
+
+
+ +

+The accept function extracts the first connection on the queue of pending connections on socket sock. +

+It then creates a new socket and returns a handle to the new socket. The newly created socket is the socket that will handle the actual the connection and has the same properties as socket sock.

+The accept function can block the caller until a connection is present if no pending connections are present on the queue.

+

Parameters:
+ + + + + +
[in] portLibrary The port library.
[in] serverSock A hysocket_t from which data will be read.
[in] addrHandle An optional pointer to a buffer that receives the address of the connecting entity, as known to the communications layer. The exact format of the addr parameter is determined by the address family established when the socket was created.
[in] sockHandle A pointer to a hysocket_t which will point to the newly created socket once accept returns successfully
+
+
Returns:
    +
  • 0 on success
  • +
  • HYPORT_ERROR_SOCKET_BADSOCKET, on generic error
  • +
  • HYPORT_ERROR_SOCKET_NOTINITIALIZED, if socket library uninitialized
  • +
  • HYPORT_ERROR_SOCKET_INTERRUPTED, the call was cancelled
  • +
  • HYPORT_ERROR_SOCKET_ADDRNOTAVAIL, the addr parameter is not valid
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMBUSY, if system busy handling other requests
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMFULL, is too many sockets are active
  • +
  • HYPORT_ERROR_SOCKET_WOULDBLOCK, the socket is marked as nonblocking and no connections are present to be accepted.,
  • +
+
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_bind (struct HyPortLibrary portLibrary,
hysocket_t  sock,
hysockaddr_t  addr 
)
+
+
+ +

+The bind function is used on an unconnected socket before subsequent calls to the connect or listen functions. +

+When a socket is created with a call to the socket function, it exists in a name space (address family), but it has no name assigned to it. Use bind to establish the local association of the socket by assigning a local name to an unnamed socket.

+

Parameters:
+ + + + +
[in] portLibrary The port library.
[in] sock hysocket_t which will be be associated with the specified name.
[in] addr Address to bind to socket.
+
+
Returns:
    +
  • 0, on success
  • +
  • HYPORT_ERROR_SOCKET_BADSOCKET, on generic error
  • +
  • HYPORT_ERROR_SOCKET_NOTINITIALIZED, if socket library uninitialized
  • +
  • HYPORT_ERROR_SOCKET_ADDRINUSE A process on the machine is already bound to the same fully-qualified address and the socket has not been marked to allow address re-use with SO_REUSEADDR.
  • +
  • HYPORT_ERROR_SOCKET_ADDRNOTAVAIL The specified address is not a valid address for this machine
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMBUSY, if system busy handling other requests
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMFULL, is too many sockets are active
  • +
  • HYPORT_ERROR_SOCKET_BADADDR, the addr parameter is not a valid part of the user address space,
  • +
+
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_close (struct HyPortLibrary portLibrary,
hysocket_t *  sock 
)
+
+
+ +

+The close function closes a socket. +

+Use it to release the socket descriptor socket so further references to socket will fail.

+

Parameters:
+ + + +
[in] portLibrary The port library.
[in] sock hysocket_t which will be closed.
+
+
Returns:
    +
  • 0, on success
  • +
  • HYPORT_ERROR_SOCKET_BADSOCKET, on generic error
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMBUSY, if system busy handling other requests
  • +
  • HYPORT_ERROR_SOCKET_WOULDBLOCK, the socket is marked as nonblocking and SO_LINGER is set to a nonzero time-out value.
  • +
+
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_connect (struct HyPortLibrary portLibrary,
hysocket_t  sock,
hysockaddr_t  addr 
)
+
+
+ +

+Establish a connection to a peer. +

+

Parameters:
+ + + + +
[in] portLibrary The port library.
[in] sock pointer to the unconnected local socket.
[in] addr pointer to the sockaddr, specifying remote host/port.
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_connect_with_timeout (struct HyPortLibrary portLibrary,
hysocket_t  sock,
hysockaddr_t  addr,
U_32  timeout,
U_32  step,
U_8 **  context 
)
+
+
+ +

+Establish a connection to a peer with a timeout. +

+This function is called repeatedly in order to carry out the connect and to allow other tasks to proceed on certain platforms. The caller must first call with step = HY_SOCK_STEP_START, if the result is HY_ERROR_SOCKET_NOTCONNECTED it will then call it with step = CHECK until either another error or 0 is returned to indicate the connect is complete. Each time the function should sleep for no more than timeout milliseconds. If the connect succeeds or an error occurs, the caller must always end the process by calling the function with step = HY_SOCK_STEP_DONE

+

Parameters:
+ + + + + + + +
[in] portLibrary The port library.
[in] sock pointer to the unconnected local socket.
[in] addr pointer to the sockaddr, specifying remote host/port.
[in] timeout timeout in milliseconds. If timeout is negative, perform a block operation.
[in] step 
[in,out] context pointer to context pointer. Filled in on first call and then to be passed into each subsequent call
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+ +
+

+ +

+
+ + + + + + + + + +
const char* VMCALL hysock_error_message (struct HyPortLibrary portLibrary  ) 
+
+
+ +

+Return an error message describing the last OS error that occurred. +

+The last error returned is not thread safe, it may not be related to the operation that failed for this thread.

+

Parameters:
+ + +
[in] portLibrary The port library
+
+
Returns:
error message describing the last OS error, may return NULL.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_fdset_init (struct HyPortLibrary portLibrary,
hysocket_t  socketP 
)
+
+
+ +

+Create a file descriptor (FD) set of one element. +

+The call may not be generally useful, as it currently only supports a single FD and is assumed to be used in conjunction with the hysock_select function.

+

Parameters:
+ + + +
[in] portLibrary The port library.
[in] socketP pointer to the socket to be added to the FD set.
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_fdset_size (struct HyPortLibrary portLibrary,
hysocket_t  handle 
)
+
+
+ +

+Answer the maximum size of the fdset currently declared for the platform. +

+This value is a parameter of the hysock_select call.

+

Parameters:
+ + + +
[in] portLibrary The port library.
[in] handle 
+
+
Returns:
the maximum size of the fdset, otherwise the (negative) error code.
+
Note:
On Unix, the value was the maximum file descriptor plus one, although on many flavors, the value is ignored in the select function. It is essential on Neutrino 2.0. On Windows, the value is ignored by the select function. On OS/2, the value is the number of file descriptors to be checked.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_free_network_interface_struct (struct HyPortLibrary portLibrary,
struct hyNetworkInterfaceArray_struct *  array 
)
+
+
+ +

+Frees the memory allocated for the hyNetworkInterface_struct array passed in. +

+

Parameters:
+ + + +
[in] portLibrary The port library.
[in] array Pointer to array of network interface structures to be freed
+
+
Returns:
0 on success
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_freeaddrinfo (struct HyPortLibrary portLibrary,
hyaddrinfo_t  handle 
)
+
+
+ +

+Frees the memory created by the call to hysock_getaddrinfo(). +

+

Parameters:
+ + + +
[in] portLibrary The port library.
[in] handle Hints on what results are returned and how the response if formed .
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+
Note:
Added for IPv6 support.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_get_network_interfaces (struct HyPortLibrary portLibrary,
struct hyNetworkInterfaceArray_struct *  array,
BOOLEAN  preferIPv4Stack 
)
+
+
+ +

+Queries and returns the information for the network interfaces that are currently active within the system. +

+Applications are responsible for freeing the memory returned via the handle.

+

Parameters:
+ + + + +
[in] portLibrary The port library.
[in,out] array Pointer to structure with array of network interface entries
[in] preferIPv4Stack boolean which indicates if we should prefer the IPv4 stack or not
+
+
Returns:
The number of elements in handle on success, negatvie portable error code on failure. -WSANO_RECOVERY if system calls required to get the info fail, -WSAENOBUFS if memory allocation fails
+
Note:
A return value of 0 indicates no interfaces exist
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo (struct HyPortLibrary portLibrary,
char *  name,
hyaddrinfo_t  hints,
hyaddrinfo_t  result 
)
+
+
+ +

+Answers a list of addresses as an opaque pointer in "result". +

+Use the following functions to extract the details:

+If the machine type supports IPv6 you can specify how you want the results returned with the following function: +
Parameters:
+ + + + + +
[in] portLibrary The port library.
[in] name The name of the host in either host name format or in IPv4 or IPv6 accepted notations.
[in] hints Hints on what results are returned and how the response if formed (can be NULL for default action).
[out] result An opaque pointer to a list of results (hyaddrinfo_struct must be preallocated).
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+
Note:
you must free the "result" structure with hysock_freeaddrinfo to free up memory. This must be done before you make a subsequent call in the same thread to this function.

+Added for IPv6 support.

+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo_address (struct HyPortLibrary portLibrary,
hyaddrinfo_t  handle,
U_8 *  address,
int  index,
U_32 *  scope_id 
)
+
+
+ +

+Answers a U_8 array representing the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0. +

+The address is in network byte order.

+The address will either be 4 or 16 bytes depending on whether it is an OS_AF_INET address or an OS_AF_INET6 address. You can check this will a call to hysock_getaddrinfo_family. Therefore you should either check the family type before preallocating the "address" or define it as 16 bytes.

+

Parameters:
+ + + + + + +
[in] portLibrary The port library.
[in] handle The result structure returned by hysock_getaddrinfo.
[out] address The address at "index" in a preallocated buffer.
[in] index The address index into the structure returned by hysock_getaddrinfo.
[out] scope_id The scope id associated with the address if applicable
+
+
Returns:
    +
  • 0, if no errors occurred, otherwise the (negative) error code
  • +
  • HYPORT_ERROR_SOCKET_VALUE_NULL when we have have the old IPv4 gethostbyname call and the address indexed is out of range. This is because the address list and the host alias list are not the same length. Just skip this entry.
  • +
+
+
Note:
Added for IPv6 support.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo_create_hints (struct HyPortLibrary portLibrary,
hyaddrinfo_t result,
I_16  family,
I_32  socktype,
I_32  protocol,
I_32  flags 
)
+
+
+ +

+Answers a hints structure as an opaque pointer in "result". +

+This hints structure is used to modify the results returned by a call to hysock_getaddrinfo. There is one of these structures per thread, so subsequent calls to this function will overwrite the same structure in memory. The structure is cached in ptBuffers and is cleared when a call to hyport_free_ptBuffer is made.

+This function is only works on IPv6 supported OS's. If it is called on an OS that does not support IPv6 then it essentially returns a NULL pointer, meaning it will have no effect on the call to hysock_getaddrinfo.

+See man pages, or MSDN doc on getaddrinfo for information on how the hints structure works.

+

Parameters:
+ + + + + + + +
[in] portLibrary The port library.
[out] result The filled in (per thread) hints structure
[in] family A address family type
[in] socktype A socket type
[in] protocol A protocol family
[in] flags Flags for modifying the result
+
+
Returns:
    +
  • 0, if no errors occurred, otherwise the (negative) error code
  • +
  • HYPORT_ERROR_SOCKET_SYSTEMFULL -- when we can't allocate memory for the ptBuffers, or the hints structure
  • +
+
+
Note:
current supported family types are:
    +
  • HYADDR_FAMILY_UNSPEC
  • +
  • HYADDR_FAMILY_AFINET4
  • +
  • HYADDR_FAMILY_AFINET6
  • +
+

+Added for IPv6 support.

+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo_family (struct HyPortLibrary portLibrary,
hyaddrinfo_t  handle,
I_32 *  family,
int  index 
)
+
+
+ +

+Answers the family type of the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0. +

+Currently the family types we support are HYSOCK_AFINET and HYSOCK_AFINET6.

+

Parameters:
+ + + + + +
[in] portLibrary The port library.
[in] handle The result structure returned by hysock_getaddrinfo.
[out] family The family at "index".
[in] index The address index into the structure returned by hysock_getaddrinfo.
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+
Note:
Added for IPv6 support.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo_length (struct HyPortLibrary portLibrary,
hyaddrinfo_t  handle,
I_32 *  length 
)
+
+
+ +

+Answers the number of results returned from hysock_getaddrinfo. +

+

Parameters:
+ + + + +
[in] portLibrary The port library.
[in] handle The result structure returned by hysock_getaddrinfo.
[out] length The number of results.
+
+
Returns:
0, if no errors occurred, otherwise the (negative) error code.
+
Note:
Added for IPv6 support.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_getaddrinfo_name (struct HyPortLibrary portLibrary,
hyaddrinfo_t  handle,
char *  name,
int  index 
)
+
+
+ +

+Answers the cannon name of the address at "index" in the structure returned from hysock_getaddrinfo, indexed starting at 0. +

+The preallocated buffer for "name" should be the size of the maximum host name: OSNIMAXHOST.

+

Parameters:
+ + + + + +
[in] portLibrary The port library.
[in] handle The result structure returned by hysock_getaddrinfo.
[out] name The name of the address at "index" in a preallocated buffer.
[in] index The address index into the structure returned by hysock_getaddrinfo.
+
+
Returns:
    +
  • 0, if no errors occurred, otherwise the (negative) error code.
  • +
  • HYPORT_ERROR_SOCKET_VALUE_NULL when we have have the old IPv4 gethostbyname call and the name indexed is out of range. This is because the address list and the host alias list are not the same length. Just skip this entry.
  • +
+
+
Note:
Added for IPv6 support.
+ +
+

+ +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
I_32 VMCALL hysock_gethostbyaddr (struct HyPortLibrary portLibrary,
char *  addr,
I_32  length,
I_32  type,
hyhostent_t  handle 
)
+
+
+ +

+Answer information on the host referred to by the address. +

+The information includes name, aliases and addresses for the nominated host (the latter being relevant on multi-homed hosts). This call has only been tested for addresses of type AF_INET.

+

Parameters:
+ + [... 2851 lines stripped ...]
[in] portLibrary The port library.