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:

• hysock_getaddrinfo_length
• hysock_getaddrinfo_name
• hysock_getaddrinfo_address
• hysock_getaddrinfo_family

If the machine type supports IPv6 you can specify how you want the results returned with the following function:

• hysock_create_getaddrinfo_hints. Passing the structure into a machine with only IPv4 support will have no effect.

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:

• if the timeout is 0, the close will block indefinitely until the messages are sent
• if the timeout is set, the close will return after the messages are sent or the timeout period expired

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:

• 0, return immediately with the status of the descriptors
• timeout, return when one of the descriptors is ready or after the timeout period has expired
• null, block indefinitely for a ready descriptor

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.

---