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:
[in] portLibrary The port library.
[in] addr Pointer to the binary-format (not null-terminated) address, in network byte order.
[in] length Length of the addr.
[in] type The type of the addr.
[out] handle Pointer to the hyhostent_struct, to be linked to the per thread platform hostent struct.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_gethostbyname ( struct HyPortLibrary portLibrary,
char *  name,
hyhostent_t  handle 
)

Answer information on the host, specified by name.

The information includes host name, aliases and addresses.

Parameters:
[in] portLibrary The port library.
[in] name The host name string.
[out] handle Pointer to the hyhostent_struct (to be linked to the per thread platform hostent struct).
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_gethostname ( struct HyPortLibrary portLibrary,
char *  buffer,
I_32  length 
)

Answer the name of the local host machine.

Parameters:
[in] portLibrary The port library.
[in,out] buffer The string buffer to receive the name
[in] length The length of the buffer
Returns:
0, if no errors occurred, otherwise the (negative) error code

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.

The preallocated buffer for "name" should be the size of the maximum host name: OSNIMAXHOST. Currently only AF_INET and AF_INET6 are supported.

Parameters:
[in] portLibrary The port library.
[in] in_addr The address we want to do a name lookup on
[in] sockaddr_size The size of "in_addr"
[out] name The hostname of the passed address in a preallocated buffer.
[in] name_length The length of the buffer pointed to by name
[in] flags Flags on how to form the repsonse (see man pages or doc for getnameinfo)
Returns:
0, if no errors occurred, otherwise the (negative) error code
Note:
Added for IPv6 support.

"flags" do not affect results on OS's that do not support the IPv6 calls.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to query for the option value.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to retrieve.
[out] optval Pointer to the boolean to update with the option value.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to query for the option value.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to retrieve.
[out] optval Pointer to the byte to update with the option value.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to query for the option value.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to retrieve.
[out] optval Pointer to the integer to update with the option value.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

See the hysock_linger_init for details of the linger behavior.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to query for the option value
[in] optlevel The level within the IP stack at which the option is defined
[in] optname The name of the option to retrieve
[out] optval Pointer to the linger struct to update with the option value
Returns:
0, if no errors occurred, otherwise the (negative) error code

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.

Currently only used to retrieve the interface of multicast sockets, but the more general call style has been used.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to query for the option value.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to retrieve.
[out] optval Pointer to the sockaddr struct to update with the option value.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_getpeername ( struct HyPortLibrary portLibrary,
hysocket_t  handle,
hysockaddr_t  addrHandle 
)

Answer the remote name for the socket.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the socket to get the address of.
[out] addrHandle Pointer to the sockaddr struct to update with the address.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_getsockname ( struct HyPortLibrary portLibrary,
hysocket_t  handle,
hysockaddr_t  addrHandle 
)

Answer the local name for the socket.

Note, the stack getsockname function actually answers a sockaddr structure, not a string name as the function name might imply.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the socket to get the address of.
[out] addrHandle Pointer to the sockaddr struct to update with the address.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

The address is in network order.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hostent struct, in which to access the addr_list.
[in] index The index of the element within the addr_list to retrieve.
Returns:
the address, in network order.

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.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hostent struct, in which to access the addr_list
[out] aliasList Pointer to the list of alternative names, to be updated
Returns:
0, if no errors occurred, otherwise the (negative) error code

I_32 VMCALL hysock_hostent_hostname ( struct HyPortLibrary portLibrary,
hyhostent_t  handle,
char **  hostName 
)

Answer the host name (string) within the argument hostent struct.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hostent struct, in which to access the hostName.
[out] hostName Host name string.
Returns:
0, the function does not validate the name access.

I_32 VMCALL hysock_htonl ( struct HyPortLibrary portLibrary,
I_32  val 
)

Answer the 32 bit host ordered argument, in network byte order.

Parameters:
[in] portLibrary The port library.
[in] val The 32 bit host ordered number.
Returns:
the 32 bit network ordered number.

U_16 VMCALL hysock_htons ( struct HyPortLibrary portLibrary,
U_16  val 
)

Answer the 16 bit host ordered argument, in network byte order.

Parameters:
[in] portLibrary The port library.
[in] val The 16 bit host ordered number.
Returns:
the 16 bit network ordered number.

I_32 VMCALL hysock_inetaddr ( struct HyPortLibrary portLibrary,
char *  addrStr,
U_32 *  addr 
)

Answer the dotted IP string as an Internet address.

Parameters:
[in] portLibrary The port library.
[out] addrStr The dotted IP string.
[in] addr Pointer to the Internet address.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_inetntoa ( struct HyPortLibrary portLibrary,
char **  addrStr,
U_32  nipAddr 
)

Answer the Internet address as a dotted IP string.

Parameters:
[in] portLibrary The port library.
[out] addrStr The dotted IP string.
[in] nipAddr The Internet address.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_ipmreq_init ( struct HyPortLibrary portLibrary,
hyipmreq_t  handle,
U_32  nipmcast,
U_32  nipinterface 
)

Initializes a new multicast membership structure.

The membership structure is used to join & leave multicast groups

See also:
hysock_setopt_ipmreq. The group may be joined using 0 (HYSOCK_INADDR_ANY) as the local interface, in which case the default local address will be used.
Parameters:
[in] portLibrary The port library.
[out] handle Pointer to the multicast membership struct.
[in] nipmcast The address, in network order, of the multicast group to join.
[in] nipinterface The address, in network order, of the local machine interface to join on.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Parameters:
[in] portLibrary The port library.
[out] handle A pointer to the hyipv6_mreq_struct to populate.
[in] ipmcast_addr The ip mulitcast address.
[in] ipv6mr_interface The ip mulitcast inteface.
Returns:
0, if no errors occurred, otherwise the (negative) error code.
Note:
Added for IPv6 support.

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.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the linger struct to be accessed.
[out] enabled Pointer to the boolean to be updated with the linger status.
Returns:
0, the function does not validate the access.

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.

Linger defines the behavior when unsent messages exist for a socket that has been sent close. If linger is disabled, the default, close returns immediately and the stack attempts to deliver unsent messages. If linger is enabled:

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the linger struct to be accessed.
[in] enabled Aero to disable, a non-zero value to enable linger.
[in] timeout 0 to linger indefinitely or a positive timeout value (in seconds).
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the linger struct to be accessed.
[out] linger Pointer to the integer, to be updated with the linger value (in seconds).
Returns:
0, the function does not validate the access.

I_32 VMCALL hysock_listen ( struct HyPortLibrary portLibrary,
hysocket_t  sock,
I_32  backlog 
)

Set the socket to listen for incoming connection requests.

This call is made prior to accepting requests, via the hysock_accept function. The backlog specifies the maximum length of the queue of pending connections, after which further requests are rejected.

Parameters:
[in] portLibrary The port library.
[in] sock Pointer to the socket to modify.
[in] backlog The maximum number of queued requests.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_ntohl ( struct HyPortLibrary portLibrary,
I_32  val 
)

Answer the 32 bit network ordered argument, in host byte order.

Parameters:
[in] portLibrary The port library.
[in] val The 32 bit network ordered number.
Returns:
the 32 bit host ordered number.

U_16 VMCALL hysock_ntohs ( struct HyPortLibrary portLibrary,
U_16  val 
)

Answer the 16-bit network ordered argument, in host byte order.

Parameters:
[in] portLibrary The port library.
[in] val The 16-bit network ordered number.
Returns:
the 16-bit host ordered number.

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.

Calling read will return as much information as is currently available up to the size of the buffer supplied. If no incoming data is available at the socket, the read call blocks and waits for data to arrive.

Parameters:
[in] portLibrary The port library.
[in] sock Pointer to the socket to read on
[out] buf Pointer to the buffer where input bytes are written
[in] nbyte The length of buf
[in] flags The flags, to influence this read (in addition to the socket options)
Returns:
  • If no error occurs, return the number of bytes received.
  • If the connection has been gracefully closed, return 0.
  • Otherwise return the (negative) error code.

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.

Calling read will return as much information as is currently available up to the size of the buffer supplied. If the information is too large for the buffer, the excess will be discarded. If no incoming data is available at the socket, the read call blocks and waits for data to arrive. It the address argument is not null, the address will be updated with address of the message sender.

Parameters:
[in] portLibrary The port library.
[in] sock Pointer to the socket to read on.
[out] buf Pointer to the buffer where input bytes are written.
[in] nbyte The length of buf.
[in] flags Tthe flags, to influence this read.
[out] addrHandle if provided, the address to be updated with the sender information.
Returns:
  • If no error occurs, return the number of bytes received.
  • If the connection has been gracefully closed, return 0.
  • Otherwise return the (negative) error code.

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.

The function is used prior to a hysock_read/readfrom, to control the period the operation may block for. Depending upon the timeout specified:

Parameters:
[in] portLibrary The port library.
[in] nfds Maximum number of file descriptors to be tested. Ignored by Windows Socket API.
[in] readfds Tthe set of descriptors to be checked if ready for read operations.
[in] writefds The set of descriptors to be checked if ready for write operations.
[in] exceptfds The set of descriptors to be checked for exceptional conditions.
[in] timeout Pointer to the timeout (a hytimeval struct).
Returns:
0 if no error occurs, otherwise return the (negative) error code.

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.

The portable version of a read operation is a blocking call (will wait indefinitely for data). This function should be called prior to a read operation, to provide a read timeout. If the result is 1, the caller is guaranteed to be able to complete a read on the socket without blocking. The actual contents of the fdset are not available for inspection (as provided in the more general 'select' function). The timeout is specified in seconds and microseconds. If the timeout is 0, skip this function (and thus the caller of a subsequent read operation may block).

Parameters:
[in] portLibrary The port library.
[in] hysocketP Pointer to the hysocket to query for available read data.
[in] secTime The integer component of the timeout periond, in seconds.
[in] uSecTime The fractional component of the timeout period, in microSeconds.
[in] accept Set to true when called for an accept(), false when called for a read()
Returns:
  • 1, if there is data available to read at the socket
  • HYPORT_ERROR_SOCKET_TIMEOUT if the call timed out
  • otherwise return the (negative) error code.

I_32 VMCALL hysock_set_nonblocking ( struct HyPortLibrary portLibrary,
hysocket_t  socketP,
BOOLEAN  nonblocking 
)

Set the nonblocking state of the socket.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to read on
[in] nonblocking Set true for nonblocking, false for blocking
Returns:
0 if no error occurs, otherwise return the (negative) error code.

I_32 VMCALL hysock_setflag ( struct HyPortLibrary portLibrary,
I_32  flag,
I_32 *  arg 
)

Ensure the flag designated is set in the argument.

This is used to construct arguments for the hysock_read/readfrom/write/writeto calls with optional flags, such as HYSOCK_MSG_PEEK.

Parameters:
[in] portLibrary The port library.
[in] flag The operation flag to set in the argument.
[in] arg Pointer to the argument to set the flag bit in.
Returns:
0 if no error occurs, otherwise return the (negative) error code.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the boolean to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the byte to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Refer to the private platformSocketLevel & platformSocketOption functions for details of the options supported.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the integer to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Currently this is used to join or leave the nominated multicast group on the local interface. It may be more generally useful, so a generic 'setop' function has been defined.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the ipmreq struct to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Currently this is used to join or leave the nominated multicast group on the local interface. It may be more generally useful, so a generic 'setop' function has been defined.t.

Supported families are OS_AF_INET and OS_AF_INET6

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the ipmreq struct to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.
Note:
Added for IPv6 support.

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.

See the hysock_linger_init for details of the linger behavior.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the linger struct to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Currently used to set the interface of multicast sockets, but the more general call style is used, in case it is more generally useful.

Parameters:
[in] portLibrary The port library.
[in] socketP Pointer to the socket to set the option in.
[in] optlevel The level within the IP stack at which the option is defined.
[in] optname The name of the option to set.
[out] optval Pointer to the hysockaddr struct to update the socket option with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_shutdown ( struct HyPortLibrary portLibrary  ) 

Terminates use of the socket library.

No sockets should be in use or the results of this operation are unpredictable. Frees any resources held by the socket library.

Parameters:
[in] portLibrary The port library.
Returns:
0, if no errors occurred, otherwise the (negative) error code

I_32 VMCALL hysock_shutdown_input ( struct HyPortLibrary portLibrary,
hysocket_t  sock 
)

The shutdown_input function disables the input stream on a socket.

Any subsequent reads from the socket will fail.

Parameters:
[in] portLibrary The port library.
[in] sock Socket to close input stream on.
Returns:
  • 0, on success
  • HYPORT_ERROR_SOCKET_OPFAILED, on generic error
  • HYPORT_ERROR_SOCKET_NOTINITIALIZED, if the library is not initialized

I_32 VMCALL hysock_shutdown_output ( struct HyPortLibrary portLibrary,
hysocket_t  sock 
)

The shutdown_output function disables the output stream on a socket.

Any subsequent writes to the socket will fail.

Parameters:
[in] portLibrary The port library.
[in] sock Socket to close output stream on.
Returns:
  • 0, on success
  • HYPORT_ERROR_SOCKET_OPFAILED, on generic error
  • HYPORT_ERROR_SOCKET_NOTINITIALIZED, if the library is not initialized

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.

The only address family currently supported is AF_INET.

Parameters:
[in] portLibrary The port library.
[out] handle Pointer to the hysockaddr struct, to be allocated.
[in] addrStr The target host, as either a name or dotted ip string.
[in] port The target port, in host order.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_sockaddr_address ( struct HyPortLibrary portLibrary,
hysockaddr_t  handle 
)

Answer the address, in network order, of the hysockaddr argument.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hysockaddr struct to access.
Returns:
the address (there is no validation on the access).

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.

Preallocated buffer "address" should be 16 bytes. "length" tells you how many bytes were used 4 or 16.

Parameters:
[in] portLibrary The port library.
[in] handle A populated hysockaddr_t.
[out] address The IPv4 or IPv6 address in network byte order.
[out] length The number of bytes of the address (4 or 16).
[out] scope_id the scope id for the address if appropriate
Returns:
0, if no errors occurred, otherwise the (negative) error code.
Note:
Added for IPv6 support.

I_32 VMCALL hysock_sockaddr_family ( struct HyPortLibrary portLibrary,
I_16 *  family,
hysockaddr_t  handle 
)

Answers the family name of a hysockaddr_struct.

Supported families are OS_AF_INET and OS_AF_INET6

Parameters:
[in] portLibrary The port library.
[out] family The family name of the address.
[in] handle A populated hysockaddr_t.
Returns:
0, if no errors occurred, otherwise the (negative) error code.
Note:
Added for IPv6 support.

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.

The only address family currently supported is AF_INET.

Parameters:
[in] portLibrary The port library.
[out] handle Pointer pointer to the hysockaddr struct, to be allocated.
[in] family The address family.
[in] nipAddr The target host address, in network order.
[in] nPort The target port, in host order.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

Pass in a hysockaddr_struct with some initial parameters to initialize it appropriately. Currently the only address families supported are OS_AF_INET6 and OS_AF_INET, which will be determined by addrlength. (4 bytes for IPv4 addresses and 16 bytes for IPv6 addresses).

Parameters:
[in] portLibrary The port library.
[out] handle Pointer pointer to the hysockaddr struct, to be allocated.
[in] addr The IPv4 or IPv6 address in network byte order.
[in] addrlength The number of bytes of the address (4 or 16).
[in] family The address family.
[in] nPort The target port, in network order.
[in] flowinfo The flowinfo value for IPv6 addresses in HOST order. Set to 0 for IPv4 addresses or if no flowinfo needs to be set for IPv6 address
[in] scope_id The scope id for an IPv6 address in HOST order. Set to 0 for IPv4 addresses and for non-scoped IPv6 addresses
[in] sock The socket that this address will be used with.
Returns:
0, if no errors occurred, otherwise the (negative) error code.
Note:
Added for IPv6 support.

U_16 VMCALL hysock_sockaddr_port ( struct HyPortLibrary portLibrary,
hysockaddr_t  handle 
)

Answer the port, in network order, of the hysockaddr argument.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hysockaddr struct to access.
Returns:
the port (there is no validation on the access).

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.

Parameters:
[in] portLibrary The port library.
[out] handle Pointer pointer to the hysocket struct, to be allocated
[in] family The address family (currently, only HYSOCK_AFINET is supported)
[in] socktype Secifies what type of socket is created
  • HYSOCK_STREAM, for a stream socket
  • HYSOCK_DGRAM, for a datagram socket
[in] protocol Type/family specific creation parameter (currently, only HYSOCK_DEFPROTOCOL supported).
Returns:
0, if no errors occurred, otherwise the (negative) error code.

I_32 VMCALL hysock_socketIsValid ( struct HyPortLibrary portLibrary,
hysocket_t  handle 
)

Determines whether or not the socket is valid.

Parameters:
[in] portLibrary The port library.
[in] handle Pointer to the hysocket struct, to be allocated.
Returns:
0 if invalid, non-zero for valid.

I_32 VMCALL hysock_startup ( struct HyPortLibrary portLibrary  ) 

Initiate the use of sockets by a process.

This function must be called before any other socket calls.

Parameters:
[in] portLibrary The port library.
Returns:
0 on success, negative error code on failure. Error code values returned are
  • HYPORT_ERROR_STARTUP_SOCK
  • HYPORT_ERROR_SOCKET_OPFAILED
  • HYPORT_ERROR_SOCKET_NOTINITIALIZED

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.

Timeval's are used as timeout arguments in the hysock_select function.

Parameters:
[in] portLibrary The port library.
[in] secTime The integer component of the timeout value (in seconds).
[in] uSecTime The fractional component of the timeout value (in microseconds).
[out] timeP Pointer pointer to the hytimeval_struct to be allocated.
Returns:
0, if no errors occurred, otherwise the (negative) error code.

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.

The successful completion of a write does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block.

Parameters:
[in] portLibrary The port library.
[in] sock Pointer to the socket to send on
[in] buf The bytes to be sent
[in] nbyte The number of bytes to send
[in] flags The flags to modify the send behavior
Returns:
If no error occur, return the total number of bytes sent, which can be less than the 'nbyte' for nonblocking sockets, otherwise the (negative) error code

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.

The successful completion of a writeto does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, writeto will block.

Parameters:
[in] portLibrary The port library.
[in] sock Pointer to the socket to send on
[in] buf The bytes to be sent
[in] nbyte The number of bytes to send
[in] flags The flags to modify the send behavior
[in] addrHandle The network address to send the datagram to
Returns:
If no error occur, return the total number of bytes sent, otherwise the (negative) error code.


Genereated on Tue Dec 9 14:12:59 2008 by Doxygen.

(c) Copyright 2005, 2008 The Apache Software Foundation or its licensors, as applicable.