TAPI for remote calls of Winsock2-specific routines

Overview

// typedefs

typedef rpc_ptr rpc_wsaevent;
typedef rpc_ptr rpc_handle;
typedef rpc_ptr rpc_overlapped;
typedef rpc_ptr rpc_hwnd;
typedef struct _rpc_qos rpc_qos;
typedef struct _rpc_sys_info rpc_sys_info;
typedef enum accept_verdict accept_verdict;
typedef struct accept_cond accept_cond;

// enums

enum {
    @69::WSA_WAIT_FAILED    = 1,
    @69::WAIT_IO_COMPLETION,
    @69::WSA_WAIT_TIMEOUT,
    @69::WSA_WAIT_EVENT_0,
};

enum accept_verdict;

// structs

struct _rpc_qos;
struct _rpc_sys_info;
struct accept_cond;

// global functions

int rpc_wsa_startup(rcf_rpc_server* rpcs);
int rpc_wsa_cleanup(rcf_rpc_server* rpcs);
int rpc_wsa_socket(rcf_rpc_server* rpcs, rpc_socket_domain domain, rpc_socket_type type, rpc_socket_proto protocol, uint8_t* info, int info_len, rpc_open_sock_flags flags);
int rpc_wsa_duplicate_socket(rcf_rpc_server* rpcs, int s, pid_t pid, uint8_t* info, int* info_len);
bool rpc_duplicate_handle(rcf_rpc_server* rpcs, pid_t src, int old_fd, pid_t tgt, int* new_fd);
bool rpc_connect_ex(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr buf, ssize_t len_buf, size_t* bytes_sent, rpc_overlapped overlapped);
bool rpc_disconnect_ex(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int flags);
int rpc_wsa_accept(rcf_rpc_server* rpcs, int s, struct sockaddr* addr, socklen_t* addrlen, socklen_t raddrlen, accept_cond* cond, int cond_num);
bool rpc_accept_ex(rcf_rpc_server* rpcs, int s, int s_a, rpc_ptr buf, size_t len, size_t laddr_len, size_t raddr_len, size_t* bytes_received, rpc_overlapped overlapped);
static size_t rpc_accept_ex_buflen(rcf_rpc_server* rpcs, size_t datalen);
void rpc_get_accept_addr_gen(rcf_rpc_server* rpcs, int s, rpc_ptr buf, size_t len, size_t laddr_len, size_t raddr_len, struct sockaddr* laddr, size_t* l_sa_len, struct sockaddr* raddr, size_t* r_sa_len);
static void rpc_get_accept_addr(rcf_rpc_server* rpcs, int s, rpc_ptr buf, size_t len, struct sockaddr* laddr, struct sockaddr* raddr);
bool rpc_transmit_packets(rcf_rpc_server* rpcs, int s, tarpc_transmit_packets_element* data, ssize_t element_count, ssize_t send_size, rpc_overlapped overlapped, ssize_t flags);
bool rpc_transmit_file(rcf_rpc_server* rpcs, int s, int file, ssize_t len, ssize_t len_per_send, rpc_overlapped overlapped, void* head, ssize_t head_len, void* tail, ssize_t tail_len, ssize_t flags);
bool rpc_transmitfile_tabufs(rcf_rpc_server* rpcs, int s, int file, ssize_t len, ssize_t bytes_per_send, rpc_overlapped overlapped, rpc_ptr head, ssize_t head_len, rpc_ptr tail, ssize_t tail_len, ssize_t flags);
int rpc_create_file(rcf_rpc_server* rpcs, char* name, rpc_cf_access_right desired_access, rpc_cf_share_mode share_mode, rpc_ptr security_attributes, rpc_cf_creation_disposition creation_disposition, rpc_cf_flags_attributes flags_attributes, int template_file);
int rpc_closesocket(rcf_rpc_server* rpcs, int s);
bool rpc_cancel_io(rcf_rpc_server* rpcs, int fd);
bool rpc_has_overlapped_io_completed(rcf_rpc_server* rpcs, rpc_overlapped overlapped);
int rpc_create_io_completion_port(rcf_rpc_server* rpcs, int file_handle, int existing_completion_port, uint64_t completion_key, unsigned int number_of_concurrent_threads);
bool rpc_get_queued_completion_status(rcf_rpc_server* rpcs, int completion_port, size_t* number_of_bytes, uint64_t* completion_key, rpc_overlapped* overlapped, unsigned int milliseconds);
bool rpc_post_queued_completion_status(rcf_rpc_server* rpcs, int completion_port, unsigned int number_of_bytes, uint64_t completion_key, rpc_overlapped overlapped);
int rpc_get_current_process_id(rcf_rpc_server* rpcs);
void rpc_get_sys_info(rcf_rpc_server* rpcs, rpc_sys_info* sys_info);
ssize_t rpc_wsa_recv_ex(rcf_rpc_server* rpcs, int s, void* buf, size_t len, rpc_send_recv_flags* flags, size_t rbuflen);
rpc_wsaevent rpc_create_event(rcf_rpc_server* rpcs);
rpc_wsaevent rpc_create_event_with_bit(rcf_rpc_server* rpcs);
bool rpc_close_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent);
bool rpc_reset_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent);
bool rpc_set_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent);
int rpc_wsa_address_to_string(rcf_rpc_server* rpcs, struct sockaddr* addr, socklen_t addrlen, uint8_t* info, int info_len, char* addrstr, ssize_t* addrstr_len);
int rpc_wsa_string_to_address(rcf_rpc_server* rpcs, char* addrstr, rpc_socket_domain address_family, uint8_t* info, int info_len, struct sockaddr* addr, socklen_t* addrlen);
int rpc_wsa_cancel_async_request(rcf_rpc_server* rpcs, rpc_handle async_task_handle);
int rpc_alloc_wsabuf(rcf_rpc_server* rpcs, size_t len, rpc_ptr* wsabuf, rpc_ptr* wsabuf_buf);
void rpc_free_wsabuf(rcf_rpc_server* rpcs, rpc_ptr wsabuf);
int rpc_wsa_connect(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr caller_wsabuf, rpc_ptr callee_wsabuf, rpc_qos* sqos);
int rpc_wsa_ioctl(rcf_rpc_server* rpcs, int s, rpc_ioctl_code control_code, char* inbuf, unsigned int inbuf_len, char* outbuf, unsigned int outbuf_len, size_t* bytes_returned, rpc_overlapped overlapped, const char* callback);
bool rpc_get_wsa_ioctl_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int* bytes, bool wait, rpc_send_recv_flags* flags, char* buf, rpc_ioctl_code control_code);
rpc_handle rpc_wsa_async_get_host_by_addr(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* addr, ssize_t addrlen, rpc_socket_type type, rpc_ptr buf, ssize_t buflen);
rpc_handle rpc_wsa_async_get_host_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, rpc_ptr buf, ssize_t buflen);
rpc_handle rpc_wsa_async_get_proto_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, rpc_ptr buf, ssize_t buflen);
rpc_handle rpc_wsa_async_get_proto_by_number(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, int number, rpc_ptr buf, ssize_t buflen);
rpc_handle rpc_wsa_async_get_serv_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, char* proto, rpc_ptr buf, ssize_t buflen);
rpc_handle rpc_wsa_async_get_serv_by_port(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, int port, char* proto, rpc_ptr buf, ssize_t buflen);
rpc_overlapped rpc_create_overlapped(rcf_rpc_server* rpcs, rpc_wsaevent hevent, unsigned int offset, unsigned int offset_high, ...);
void rpc_delete_overlapped(rcf_rpc_server* rpcs, rpc_overlapped overlapped);
int rpc_wsa_send(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, rpc_send_recv_flags flags, ssize_t* bytes_sent, rpc_overlapped overlapped, const char* callback);
int rpc_wsa_recv(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, size_t riovcnt, rpc_send_recv_flags* flags, ssize_t* bytes_received, rpc_overlapped overlapped, const char* callback);
int rpc_wsa_send_to(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, rpc_send_recv_flags flags, ssize_t* bytes_sent, const struct sockaddr* to, rpc_overlapped overlapped, const char* callback);
int rpc_wsa_recv_from(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, size_t riovcnt, rpc_send_recv_flags* flags, ssize_t* bytes_received, struct sockaddr* from, socklen_t* fromlen, rpc_overlapped overlapped, const char* callback);
int rpc_wsa_send_disconnect(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov);
int rpc_wsa_recv_disconnect(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov);
int rpc_wsa_recv_msg(rcf_rpc_server* rpcs, int s, struct rpc_msghdr* msg, ssize_t* bytes_received, rpc_overlapped overlapped, const char* callback);
bool rpc_wsa_get_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, size_t* bytes, bool wait, rpc_send_recv_flags* flags, char* buf, int buflen);
int rpc_completion_callback(rcf_rpc_server* rpcs, int* called, int* error, ssize_t* bytes, rpc_overlapped* overlapped);
static void rpc_cleanup_completion_callback(rcf_rpc_server* rpcs);
int rpc_wsa_event_select(rcf_rpc_server* rpcs, int s, rpc_wsaevent event_object, rpc_network_event event);
int rpc_enum_network_events(rcf_rpc_server* rpcs, int s, rpc_wsaevent event_object, struct tarpc_network_events* events);
static const char* wsa_wait_rpc2str(int code);
int rpc_wait_for_multiple_events(rcf_rpc_server* rpcs, int count, rpc_wsaevent* events, bool wait_all, uint32_t timeout, bool alertable);
rpc_hwnd rpc_create_window(rcf_rpc_server* rpcs);
void rpc_destroy_window(rcf_rpc_server* rpcs, rpc_hwnd hwnd);
int rpc_wsa_async_select(rcf_rpc_server* rpcs, int s, rpc_hwnd hwnd, rpc_network_event event);
int rpc_peek_message(rcf_rpc_server* rpcs, rpc_hwnd hwnd, int* s, rpc_network_event* event);
bool rpc_is_winsock2(rcf_rpc_server* rpcs);
int rpc_wsa_join_leaf(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr caller_wsabuf, rpc_ptr callee_wsabuf, rpc_qos* sqos, rpc_join_leaf_flags flags);
bool rpc_read_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* received, rpc_overlapped overlapped);
bool rpc_write_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* sent, rpc_overlapped overlapped);
bool rpc_read_file_ex(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, rpc_overlapped overlapped, const char* callback);
bool rpc_write_file_ex(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, rpc_overlapped overlapped, const char* callback);
int rpc_overfill_buffers_ex(rcf_rpc_server* rpcs, int sock, uint64_t* sent, bool is_nonblocking);
static const char* wsa_name_convert(const char* name);

// macros

#define RCF_RPC_MAX_ACCEPT_CONDS
#define RPC_WSA_IOCTL_OUTBUF_MAX

Detailed Documentation

Typedefs

typedef rpc_ptr rpc_wsaevent

Windows Event Objects

typedef rpc_ptr rpc_handle

HANDLE

typedef rpc_ptr rpc_overlapped

Windows WSAOVERLAPPED structure

typedef rpc_ptr rpc_hwnd

Windows HWND

typedef struct _rpc_qos rpc_qos

Windows QOS structure

typedef enum accept_verdict accept_verdict

Accept decision making

typedef struct accept_cond accept_cond

Accept Condition

Global Functions

int rpc_wsa_startup(rcf_rpc_server* rpcs)

WSAStartup() remote call.

Parameters:

rpcs	RPC server handle

Returns:

Zero if successful.

int rpc_wsa_cleanup(rcf_rpc_server* rpcs)

WSACleanup() remote call.

Parameters:

rpcs	RPC server handle

Returns:

Zero if successful.

int rpc_wsa_socket(rcf_rpc_server* rpcs, rpc_socket_domain domain, rpc_socket_type type, rpc_socket_proto protocol, uint8_t* info, int info_len, rpc_open_sock_flags flags)

WSASocket() remote call.

Parameters:

rpcs	RPC server handle
domain	communication domain
type	type specification of the new socket
protocol	specifies the protocol to be used
info	pointer to an object than defines the characteristics of the created socket
info_len	length of info
flags	flags for socket creation (overlapped, multipoint, etc.)

Returns:

Socket descriptor upon successful completion, otherwise -1 is returned.

int rpc_wsa_duplicate_socket(rcf_rpc_server* rpcs, int s, pid_t pid, uint8_t* info, int* info_len)

WSADuplicateSocket() remote call. Protocol info is copied to the Test Engine and then back to the TA (in rpc_wsa_socket() function) as is.

Parameters:

rpcs	RPC server
s	old socket
pid	destination process PID
info	buffer for protocol info or NULL
info_len	buffer length location (IN)/protocol info length location (OUT)

Returns:

Value returned by WSADuplicateSocket() function

bool rpc_duplicate_handle(rcf_rpc_server* rpcs, pid_t src, int old_fd, pid_t tgt, int* new_fd)

DuplicateHandle() remote call.

bInheritHandle is true, dwOptions is DUPLICATE_SAME_ACCESS

Parameters:

rpcs	RPC server
src	source process PID
old_fd	old socket
tgt	target process PID
new_fd	new socket location

Returns:

Value returned by DuplicateHandle() function

bool rpc_connect_ex(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr buf, ssize_t len_buf, size_t* bytes_sent, rpc_overlapped overlapped)

Establish a connection to a specified socket, and optionally send data once connection is established.

Parameters:

rpcs	RPC server handle
s	socket descriptor
addr	pointer to a sockaddr structure containing the address to connect to.
buf	RPC pointer to buffer containing connect data
len_buf	length of the buffer buf
bytes_sent	pointer a the number of bytes sent
overlapped	overlapped object or RPC_NULL

Returns:

Value returned by ConnectEx()

bool rpc_disconnect_ex(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int flags)

Close connection to a socket and allow the socket handle to be reused.

Parameters:

rpcs	RPC server handle
s	conencted socket descriptor
overlapped	overlapped object or RPC_NULL
flags	customize behavior of operation

Returns:

Value returned by DisconnectEx()

int rpc_wsa_accept(rcf_rpc_server* rpcs, int s, struct sockaddr* addr, socklen_t* addrlen, socklen_t raddrlen, accept_cond* cond, int cond_num)

WSAAccept() with condition function support. List of conditions describes the condition function behavior.

Parameters:

rpcs	RPC server handle (IN)
s	listening socket descriptor (IN)
addr	pointer to a sockaddr structure containing the address of the peer entity (OUT)
addrlen	pointer to the length of the address addr
raddrlen	real length of the address addr
cond	specified condition that makes decision based on the caller information passed in as parameters.
cond_num	number of conditions

Returns:

New connected socket upon successful completion, otherwise -1 is returned

bool rpc_accept_ex(rcf_rpc_server* rpcs, int s, int s_a, rpc_ptr buf, size_t len, size_t laddr_len, size_t raddr_len, size_t* bytes_received, rpc_overlapped overlapped)

Client implementation of AcceptEx()- GetAcceptExSockAddr() call.

Parameters:

rpcs	RPC server
s	descriptor of socket that has already been called with the listen function
s_a	descriptor idenfifying a socket on which to accept an incoming connection
buf	RPC pointer to the buffer to receive data
len	length of the buffer to receive data (should not include the size of local and remote addresses)
laddr_len	length of the local address
raddr_len	length of the remote address
bytes_received	number of received data bytes
overlapped	overlapped object or RPC_NULL

Returns:

Value returned by AcceptEx() function.

static size_t rpc_accept_ex_buflen(rcf_rpc_server* rpcs, size_t datalen)

Calculate length of buffer to be allocated for rpc_accept_ex().

Parameters:

rpcs	RPC server
datalen	space required for data

Returns:

Amount of space required for data and addresses.

void rpc_get_accept_addr_gen(rcf_rpc_server* rpcs, int s, rpc_ptr buf, size_t len, size_t laddr_len, size_t raddr_len, struct sockaddr* laddr, size_t* l_sa_len, struct sockaddr* raddr, size_t* r_sa_len)

GetAcceptExSockAddr() remote call.

Parameters:

rpcs	RPC server
s	descriptor of socket that was passed to rpc_accept_ex() fuinction as 3d parameter
buf	pointer to a buffer passed to rpc_wsa_get_overlapped_result()
len	buffer size passed to AcceptEx()
laddr_len	length of the local address passed to AcceptEx()
raddr_len	length of the remote address passed to AcceptEx()
laddr	local address returned by GetAcceptExSockAddr()
l_sa_len	LocalSockaddrLen (passed transparently)
raddr	remote address returned by GetAcceptExSockAddr()
r_sa_len	RemoteSockaddrLen (passed transparently)

static void rpc_get_accept_addr(rcf_rpc_server* rpcs, int s, rpc_ptr buf, size_t len, struct sockaddr* laddr, struct sockaddr* raddr)

GetAcceptExSockAddr() remote call.

Parameters:

rpcs	RPC server
s	descriptor of socket that was passed to rpc_accept_ex() fuinction as 3d parameter
buf	pointer to a buffer passed to rpc_wsa_get_overlapped_result()
len	buffer size wich was passed to rpc_accept_ex()
laddr	local address returned by GetAcceptExSockAddr()
raddr	remote address returned by GetAcceptExSockAddr()

bool rpc_transmit_packets(rcf_rpc_server* rpcs, int s, tarpc_transmit_packets_element* data, ssize_t element_count, ssize_t send_size, rpc_overlapped overlapped, ssize_t flags)

Transmit data over a connected socket. Data can be transferred from memory or from file(s).

Parameters:

rpcs	RPC server handle
s	connected socket descriptor
data	structure describing data sources
element_count	quantity of data sources
send_size	size of data sent by one pass
overlapped	overlapped object or RPC_NULL
flags	call flags

Returns:

true if data were successfully sent, false if some error occurred (and errno is set to respective value)

bool rpc_transmit_file(rcf_rpc_server* rpcs, int s, int file, ssize_t len, ssize_t len_per_send, rpc_overlapped overlapped, void* head, ssize_t head_len, void* tail, ssize_t tail_len, ssize_t flags)

Transmit file data over a connected socket. This function uses the operating system cache manager to retrive the file data, and perform high-performance file data transfert over sockets.

Parameters:

rpcs	RPC server handle
s	connected socket descriptor
file	handle of the file containing the data to be transmited; should be got by rpc_create_file().
len	length of data to transmit
len_per_send	size of each block of data in each send operation.
overlapped	overlapped object or RPC_NULL
head	pointer to a buffer to be transmitted before file data is transmitted
head_len	size of buffer head
tail	pointer to a buffer to be transmitted after transmission of file data.
tail_len	size of buffer tail
flags	call flags (See Transmit file for more information)

Returns:

Value returned by TransmitFile()

bool rpc_transmitfile_tabufs(rcf_rpc_server* rpcs, int s, int file, ssize_t len, ssize_t bytes_per_send, rpc_overlapped overlapped, rpc_ptr head, ssize_t head_len, rpc_ptr tail, ssize_t tail_len, ssize_t flags)

Transmit file data over a connected socket. This function uses the operating system cache manager to retrive the file data, and perform high-performance file data transfert over sockets.

ATTENTION: when using the overlapped I/O the supplied buffers head and tail will be freed when you call rpc_wsa_get_overlapped_result().

Parameters:

rpcs	RPC server handle.
s	connected socket descriptor.
file	handle of the file containing the data to be transmited; should be got by rpc_create_file().
len	amount of file data to transmit.
bytes_per_send	size of each block of data in each send operation.
overlapped	overlapped object or RPC_NULL
head	a pointer valid in the TA virtual address space and pointing to a buffer to be transmitted before the file data.
head_len	size of buffer head.
tail	a pointer valid in the TA virtual address space and pointing to a buffer to be transmitted after the file data.
tail_len	size of buffer tail.
flags	TransmitFile call flags.

Returns:

true in case of success, false otherwise.

int rpc_create_file(rcf_rpc_server* rpcs, char* name, rpc_cf_access_right desired_access, rpc_cf_share_mode share_mode, rpc_ptr security_attributes, rpc_cf_creation_disposition creation_disposition, rpc_cf_flags_attributes flags_attributes, int template_file)

CreateFile() remote call.

Parameters:

rpcs	RPC server handle.
name	Null-terminated string - the name of object to create or open.
desired_access	The access to object.
share_mode	The sharing mode of object.
security_attributes	TA-side pointer to a Windows SECURITY_ATTRIBUTES structure.
creation_disposition	An action to take on files that exist and do not exist.
flags_attributes	The file attributes and flags.
template_file	TA-side handle to a template file.

Returns:

TA-side handle of the object, otherwise -1.

int rpc_closesocket(rcf_rpc_server* rpcs, int s)

closesocket() remote call.

Parameters:

rpcs	RPC server handle
s	Socket to close

Returns:

Non-zero on success, zero otherwise.

bool rpc_cancel_io(rcf_rpc_server* rpcs, int fd)

CancelIo() remote call.

Parameters:

rpcs	RPC server handle
fd	File handle which requests to be cancelled belong to

Returns:

true (success) or false (failure)

bool rpc_has_overlapped_io_completed(rcf_rpc_server* rpcs, rpc_overlapped overlapped)

HasOverlappedIoCompleted() remote call.

Parameters:

rpcs	RPC server handle
overlapped	overlapped object or RPC_NULL

Returns:

true if overlapped I/O has completed, false otherwise.

int rpc_create_io_completion_port(rcf_rpc_server* rpcs, int file_handle, int existing_completion_port, uint64_t completion_key, unsigned int number_of_concurrent_threads)

CreateIoCompletionPort() remote call.

Parameters:

rpcs	RPC server handle
file_handle	Handle of a file/socket opened for overlapped I/O
existing_completion_port	Handle of the existing completion port.
completion_key	Per-file completion key.
number_of_concurrent_threads	Maximum number of thread that the OS can allow to concurrently process completion packets for the I/O completion port.

Returns:

Completion port handle on success, 0 otherwise

bool rpc_get_queued_completion_status(rcf_rpc_server* rpcs, int completion_port, size_t* number_of_bytes, uint64_t* completion_key, rpc_overlapped* overlapped, unsigned int milliseconds)

GetQueuedCompletionStatus() remote call.

Parameters:

rpcs	RPC server handle
completion_port	Handle of the existing completion port
number_of_bytes	Where to store the number of bytes transferred during the I/O operation
completion_key	Where to store the completion key value associated with the file handle whose I/O has completed
overlapped	overlapped object or RPC_NULL
milliseconds	Timeout to wait for the I/O completion.

Returns:

Non-zero on success, zero otherwise

bool rpc_post_queued_completion_status(rcf_rpc_server* rpcs, int completion_port, unsigned int number_of_bytes, uint64_t completion_key, rpc_overlapped overlapped)

PostQueuedCompletionStatus() remote call.

Parameters:

rpcs	RPC server handle
completion_port	Handle of the existing completion port
number_of_bytes	Number of bytes transferred
completion_key	Completion key value
overlapped	overlapped object or RPC_NULL

Returns:

Non-zero on success, zero otherwise

int rpc_get_current_process_id(rcf_rpc_server* rpcs)

GetCurrentProcessId() remote call.

Parameters:

rpcs	RPC server handle

Returns:

The specified RPC server process identifier.

void rpc_get_sys_info(rcf_rpc_server* rpcs, rpc_sys_info* sys_info)

Get various system information of the host where the specified RPC server runs.

Parameters:

rpcs	RPC server handle
sys_info	where to store the obtained system information.

ssize_t rpc_wsa_recv_ex(rcf_rpc_server* rpcs, int s, void* buf, size_t len, rpc_send_recv_flags* flags, size_t rbuflen)

WSARecvEx() remote call.

Parameters:

rpcs	RPC server handle
s	socket descriptor
buf	pointer to a buffer containing the incoming data
len	Maximum length of expected data
flags	specify whether data is fully or partially received
rbuflen	real size of buffer buf

Returns:

Number of bytes received upon successful completion. If the connection has been close it returned zero. Otherwise -1 is returned.

rpc_wsaevent rpc_create_event(rcf_rpc_server* rpcs)

Create a new event object.

Parameters:

rpcs	RPC server handle

Returns:

Upon successful completion this function returns an rpc_wsaevent structure handle, otherwise NULL is returned

rpc_wsaevent rpc_create_event_with_bit(rcf_rpc_server* rpcs)

Create a new event object and set lower bit.

Parameters:

rpcs	RPC server handle

Returns:

Upon successful completion this function returns an rpc_wsaevent structure handle, otherwise NULL is returned

bool rpc_close_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent)

Close an open event object handle.

Parameters:

rpcs	RPC server handle
hevent	handle of the event to be close

Returns:

value returned by WSACloseEvent()

bool rpc_reset_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent)

Reset the state of the specified event object to non-signaled.

Parameters:

rpcs	RPC server handle
hevent	event object handle

Returns:

Value returned by WSAResetEvent()

bool rpc_set_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent)

Set the state of the specified event object to signaled.

Parameters:

rpcs	RPC server handle
hevent	event object handle

Returns:

Value returned by WSASetEvent()

int rpc_wsa_address_to_string(rcf_rpc_server* rpcs, struct sockaddr* addr, socklen_t addrlen, uint8_t* info, int info_len, char* addrstr, ssize_t* addrstr_len)

Convert a sockaddr structure to its string representation.

Parameters:

rpcs	RPC server handle
addr	pointer to the sockaddr structure to be converted
addrlen	length of the address addr
info	pointer to an object which is associated with the provider to be used or NULL
info_len	length of object info (if not NULL)
addrstr	buffer that contain the string representation of the specified address (OUT)
addrstr_len	length of buffer addrstr

Returns:

0 on success or -1 on failure

int rpc_wsa_string_to_address(rcf_rpc_server* rpcs, char* addrstr, rpc_socket_domain address_family, uint8_t* info, int info_len, struct sockaddr* addr, socklen_t* addrlen)

Convert a numeric string to a sockaddr structure.

Parameters:

rpcs	RPC server handle
addrstr	numeric address string
address_family	address family to which the string belongs
info	pointer to an object which is associated with the provider to be used or NULL
info_len	length of object info (if not null)
addr	pointer to a sockaddr structure that receive the converted address.
addrlen	points to the length of addr

Returns:

0 on success or -1 on failure

int rpc_wsa_cancel_async_request(rcf_rpc_server* rpcs, rpc_handle async_task_handle)

Cancel an incomplete asynchronous task.

Parameters:

rpcs	RPC server handle
async_task_handle	task to be canceled

Returns:

0 on success or -1 on failure

int rpc_alloc_wsabuf(rcf_rpc_server* rpcs, size_t len, rpc_ptr* wsabuf, rpc_ptr* wsabuf_buf)

Allocate a WSABUF structure, a buffer of specified length and fill in the fields of allocated structure according to the allocated buffer pointer and length in the TA address space.

Parameters:

rpcs	RPC server handle
len	length of WSABUF buffer field
wsabuf	pointer to a WSABUF structure
wsabuf_buf	pointer to the buffer whose length is len

Returns:

0 on success or -1 on failure

void rpc_free_wsabuf(rcf_rpc_server* rpcs, rpc_ptr wsabuf)

Free a previously allocated by rpc_alloc_wsabuf buffer.

Parameters:

rpcs	RPC server handle
wsabuf	pointer to the buffer to be freed

int rpc_wsa_connect(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr caller_wsabuf, rpc_ptr callee_wsabuf, rpc_qos* sqos)

WSAConnect() remote call.

Parameters:

rpcs	RPC server handle
s	Descriptor identifying an unconnected socket
addr	pointer to a sockaddr structure containing the address to connect to
caller_wsabuf	TA virtual address space valid pointer to a WSABUF structure describing the user data that is to be transferred to the other socket during connection establishment
callee_wsabuf	TA virtual address space valid pointer to a WSABUF structure describing the user data that is to be transferred back from the other socket during connection establishment.
sqos	TA virtual address space valid pointer to a QOS structure for socket s.

Returns:

0 in case of success, nonzero otherwise.

int rpc_wsa_ioctl(rcf_rpc_server* rpcs, int s, rpc_ioctl_code control_code, char* inbuf, unsigned int inbuf_len, char* outbuf, unsigned int outbuf_len, size_t* bytes_returned, rpc_overlapped overlapped, const char* callback)

WSAIoctl() remote call.

If input/output argument is list of addresses, buffer should contain array of sockaddr_storage structures. If input/output argument is QOS, rpc_qos structure should be in the buffer. If input/output argument is keepalive or GUID, corresponding tarpc_* structures should be in the buffer.

Parameters:

rpcs	RPC server handle
s	Descriptor identifying a socket
control_code	Control code of operation to perform
inbuf	Pointer to the input buffer with correct data
inbuf_len	Size of the input buffer to be passed to WSAIoctl()
outbuf	Pointer to the output buffer big enough to decode any result (if length of decoded result is greater than RPC_WSA_IOCTL_OUTBUF_MAX, error is returned)
outbuf_len	Size of the output buffer to be passed to WSAIoctl()
bytes_returned	Pointer to the actual number of bytes of output (filled by WSAIoctl())
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 in case of success, nonzero otherwise.

bool rpc_get_wsa_ioctl_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int* bytes, bool wait, rpc_send_recv_flags* flags, char* buf, rpc_ioctl_code control_code)

Retrieve the result of the preceding overlapped WSAIoctl() call.

Parameters:

rpcs	RPC server handle
s	desccriptor identifying a socket
overlapped	overlapped object or RPC_NULL
bytes	pointer to the variable that will accept the number of bytes returned in buf
wait	specifies whether the function should wait for the overlapped operation to complete (should wait, if true)
flags	pointer to a variable that will receive one or more flags that supplement the completion status
buf	pointer to a buffer containing result data
control_code	the control code the preceding WSAIoctl() call has been called with

Returns:

Nonzero in case of success, otherwise 0.

rpc_handle rpc_wsa_async_get_host_by_addr(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* addr, ssize_t addrlen, rpc_socket_type type, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve host information by given address. See WSAAsyncGetHostByAddr().

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
addr	pointer to the network address of the host
addrlen	size of addr
type	type of the address
buf	valid buffer pointer in the TA address space. Contain the host entry data
buflen	size of the buffer buf, in bytes

Returns:

Value returned by WSAAsyncGetHostByAddr()

rpc_handle rpc_wsa_async_get_host_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve host information by given name. See WSAAsyncGetHostByName().

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
name	pointer to the host name
buf	valid buffer pointer in the TA address space. Contain the host entry data
buflen	size of the buffer buf, in bytes

Returns:

Value returned by WSAAsyncGetHostByName()

rpc_handle rpc_wsa_async_get_proto_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve protocol information by given name. See WSAAsyncGetProtoByName().

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
name	pointer to a null-terminated protocol name
buf	valid buffer pointer in the TA address space. Contain the protocol entry data
buflen	size of the buffer buf, in bytes

Returns:

Value returned by WSAAsyncGetProtoByName()

rpc_handle rpc_wsa_async_get_proto_by_number(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, int number, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve protocol information by given number. See WSAAsyncGetProtoByNumber().

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
number	protocol number in host byte order
buf	valid buffer pointer in the TA address space. Contain the protocol entry data
buflen	size of the buffer buf, in bytes

Returns:

Value returned by WSAAsyncGetProtoByNumber()

rpc_handle rpc_wsa_async_get_serv_by_name(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, char* name, char* proto, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve service information that corresponds to a service name.

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
name	pointer to a null-terminated service name
proto	pointer to a protocol name
buf	valid buffer pointer in the TA address space. Contain the service entry data
buflen	size of the buffer buf, in bytes

Returns:

Value returned by WSAAsyncGetServByName()

rpc_handle rpc_wsa_async_get_serv_by_port(rcf_rpc_server* rpcs, rpc_hwnd hwnd, unsigned int wmsg, int port, char* proto, rpc_ptr buf, ssize_t buflen)

Asynchronously retrieve service information that corresponds to a port and protocol.

Parameters:

rpcs	RPC server handle
hwnd	handle to a window that receive a message when the asynchronous request completes
wmsg	message to be received when asynchronous request completes
port	port for the service
proto	pointer to a protocol name
buf	valid buffer pointer in the TA address space. Contain the service entry data
buflen	size of the buffer buf, in bytes

Returns:

value returned by WSAAsyncGetServByName()

rpc_overlapped rpc_create_overlapped(rcf_rpc_server* rpcs, rpc_wsaevent hevent, unsigned int offset, unsigned int offset_high, ...)

Create WSAOVERLAPPED structure on TA side.

Parameters:

rpcs	RPC server handle
hevent	handle to an event object
offset	position at which to start the transfert
offset_high	high-order word of the position at which to start the transfert
…	cookie1 and cookie2 may be passed

Returns:

WSAOVERLAPPED structure upon successful completion or RPC_NULL

void rpc_delete_overlapped(rcf_rpc_server* rpcs, rpc_overlapped overlapped)

Delete specified WSAOVERLAPPED structure.

Parameters:

rpcs	RPC server handle
overlapped	overlapped object

int rpc_wsa_send(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, rpc_send_recv_flags flags, ssize_t* bytes_sent, rpc_overlapped overlapped, const char* callback)

Send data on a connected socket.

Parameters:

rpcs	RPC server handle
s	connected socket descriptor
iov	pointer to a vector of buffers containing the data to be sent
iovcnt	number of buffers in the vector
flags	modifies the behavior of the call.
bytes_sent	pointer to the number of bytes sent
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 on success or -1 on failure

int rpc_wsa_recv(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, size_t riovcnt, rpc_send_recv_flags* flags, ssize_t* bytes_received, rpc_overlapped overlapped, const char* callback)

Receive data from a connected socket.

Parameters:

rpcs	RPC server handle
s	connected socket descriptor
iov	pointer to a vector of buffers where received data have to be stored
iovcnt	number of buffers in the vector iov
riovcnt	number of buffers to receive
flags	modifies the behavior of the call. (See rpc_send_recv_flags)
bytes_received	pointer to the number of bytes received
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 on success or -1 on failure

int rpc_wsa_send_to(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, rpc_send_recv_flags flags, ssize_t* bytes_sent, const struct sockaddr* to, rpc_overlapped overlapped, const char* callback)

Send data to a specified destination.

Parameters:

rpcs	RPC server handle
s	descriptor identifying a possibly connected socket
iov	pointer to a vector of buffers containing the data to be sent
iovcnt	number of buffer in the vector iov
flags	modifies the behavior of the call. (See rpc_send_recv_flags)
bytes_sent	pointer to the number of bytes sent
to	pointer to the address of the target socket
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 on success or -1 on failure

int rpc_wsa_recv_from(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov, size_t iovcnt, size_t riovcnt, rpc_send_recv_flags* flags, ssize_t* bytes_received, struct sockaddr* from, socklen_t* fromlen, rpc_overlapped overlapped, const char* callback)

Receive datagram from socket.

Parameters:

rpcs	RPC server handle
s	descriptor identifying a socket
iov	pointer to a vector of buffers where received data have to be stored
iovcnt	number of buffers in the vector iov
riovcnt	number of buffers to receive
flags	modifies the behavior of the call. (See rpc_send_recv_flags)
bytes_received	pointer to the number of bytes received
from	pointer to a buffer that hold the source address upon the completion of overlapped operation
fromlen	size of the address from
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 on success or -1 on failure

int rpc_wsa_send_disconnect(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov)

Initiate termination of the connection for the socket and send disconnect data.

Parameters:

rpcs	RPC server handle
s	descriptor identifying a socket
iov	vector of buffers containing the disconnect data

Returns:

0 on success or -1 on failure

int rpc_wsa_recv_disconnect(rcf_rpc_server* rpcs, int s, const struct rpc_iovec* iov)

Terminate reception on a socket, and retrieve disconnect data in case of connection oriented socket.

Parameters:

rpcs	RPC server handle
s	descriptor identifying a socket
iov	vector of buffers containing the disconnect data

Returns:

0 on success or -1 on failure

int rpc_wsa_recv_msg(rcf_rpc_server* rpcs, int s, struct rpc_msghdr* msg, ssize_t* bytes_received, rpc_overlapped overlapped, const char* callback)

Retrieve data and control information from connected or unconnected sockets.

Parameters:

rpcs	RPC server handle
s	descriptor identifying a socket
msg	pointer to a rpc_msghdr structure containing received data
bytes_received	pointer to the number of bytes received
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

0 on success or -1 on failure

bool rpc_wsa_get_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, size_t* bytes, bool wait, rpc_send_recv_flags* flags, char* buf, int buflen)

Retrieve the result of an overlapped operation on a specified socket.

Parameters:

rpcs	RPC server handle
s	desccriptor identifying a socket
overlapped	overlapped object or RPC_NULL
bytes	pointer to the number of bytes that were transfered by a send or receive operation
wait	specifies whether the function should wait for the overlapped operation to complete (should wait, if true)
flags	pointer to a variable that will receive one or more flags that supplement the completion status
buf	pointer to a buffer containing result data
buflen	size of buffer buf

Returns:

true on success, false on failure

int rpc_completion_callback(rcf_rpc_server* rpcs, int* called, int* error, ssize_t* bytes, rpc_overlapped* overlapped)

Get result of completion callback (if called).

Parameters:

rpcs	RPC server handle
called	number of callback calls since last call of this function
bytes	number of tramsmitted bytes reported to last callback
error	overlapped operation error reported to the last callback
overlapped	overlapped object reported to the last callback

Returns:

0 (success) or -1 (failure)

static void rpc_cleanup_completion_callback(rcf_rpc_server* rpcs)

Cleanup completion callback statistics.

Parameters:

rpcs	RPC server handle

int rpc_wsa_event_select(rcf_rpc_server* rpcs, int s, rpc_wsaevent event_object, rpc_network_event event)

Specify an event object to be associated with the specified set of network events.

Parameters:

rpcs	RPC server handle
s	socket descriptor
event_object	event object
event	bitmask the specifies the combination of network events

Returns:

0 on success or -1 on failure

int rpc_enum_network_events(rcf_rpc_server* rpcs, int s, rpc_wsaevent event_object, struct tarpc_network_events* events)

WSAEnumNetworkEvents() remote call.

Parameters:

rpcs	RPC server
s	socket descriptor
event_object	event object to be reset
events	network events that occurred

Returns:

Value returned by WSAEnumNetworkEvents() function

static const char* wsa_wait_rpc2str(int code)

Convert WSAWaitForMultipleEvents() return code to a string

Parameters:

code	code to be converted

Returns:

string representation of the event

int rpc_wait_for_multiple_events(rcf_rpc_server* rpcs, int count, rpc_wsaevent* events, bool wait_all, uint32_t timeout, bool alertable)

WSAWaitForMultipleEvents() remote call.

Parameters:

rpcs	RPC server handle
count	number of events in events
events	pointer to an array of events
wait_all	wait type, when true the function return when the state of all events is signaled
timeout	time-out interval, milliseconds. If the interval expires, the function return. If timeout is zero the function tests the state of specified event objects and returns immediately. If timeout is WSA_INFINITE, the time-out interval never expires.
alertable	specify whether the completion routine has to be executed before the function returns.

Returns:

The event object that make the function to return. -1 is returned in the case of RPC error

rpc_hwnd rpc_create_window(rcf_rpc_server* rpcs)

Create a window for receiving event notifications.

Parameters:

rpcs	RPC server handle

Returns:

handle of the created window, upon successful completion, otherwise NULL is returned

void rpc_destroy_window(rcf_rpc_server* rpcs, rpc_hwnd hwnd)

Destroy the specified window.

Parameters:

rpcs	RPC server handle
hwnd	handle of window to be destroyed

int rpc_wsa_async_select(rcf_rpc_server* rpcs, int s, rpc_hwnd hwnd, rpc_network_event event)

Request window-based notification of network events for a socket.

Parameters:

rpcs	RPC server handle
s	socket descriptor
hwnd	handle of the window which receives message when a network event occurs
event	bitmask that specifies a combination of network events

Returns:

0 on success or -1 on failure

int rpc_peek_message(rcf_rpc_server* rpcs, rpc_hwnd hwnd, int* s, rpc_network_event* event)

Check the thread message queue for a posted message and retrieve the message, if any exist

Parameters:

rpcs	RPC server handle
hwnd	handle of the windows whose messages are to be examinied
s	socket descriptor whose event causes message notification
event	pointer to the bitmask that specifies a combination of network events

Returns:

Value returned by PeekMessage()

bool rpc_is_winsock2(rcf_rpc_server* rpcs)

Check, if RPC server is located on TA with winsock2.

Parameters:

rpcs	RPC server handle

Returns:

true, if it is definitely known that winsock2 is used and false otherwise

int rpc_wsa_join_leaf(rcf_rpc_server* rpcs, int s, const struct sockaddr* addr, rpc_ptr caller_wsabuf, rpc_ptr callee_wsabuf, rpc_qos* sqos, rpc_join_leaf_flags flags)

Joins a leaf node into a multipoint session.

Parameters:

rpcs	RPC server handle
s	Descriptor identifying an unconnected socket
addr	pointer to a sockaddr structure containing the address to connect to
caller_wsabuf	TA virtual address space valid pointer to a WSABUF structure describing the user data that is to be transferred to the other socket during connection establishment
callee_wsabuf	TA virtual address space valid pointer to a WSABUF structure describing the user data that is to be transferred back from the other socket during connection establishment.
sqos	TA virtual address space valid pointer to a QOS structure for socket s.
flag	Flag to indicate that the socket is acting as a sender (JL_SENDER_ONLY), receiver (JL_RECEIVER_ONLY), or both (JL_BOTH).

Returns:

The value of type SOCKET that is a descriptor for the newly created multipoint socket in case of success, a value of INVALID_SOCKET otherwise.

bool rpc_read_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* received, rpc_overlapped overlapped)

ReadFile() remote call.

Parameters:

rpcs	RPC server handle
fd	file descriptor
buf	buffer for data
count	number of bytes to be read
received	location for number of read bytes
overlapped	overlapped object or RPC_NULL

Returns:

true (success) or false (failure)

bool rpc_write_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* sent, rpc_overlapped overlapped)

WriteFile() remote call.

Parameters:

rpcs	RPC server handle
fd	file descriptor
buf	buffer for data
count	number of bytes to be sent
sent	location for number of sent bytes
overlapped	overlapped object or RPC_NULL

Returns:

true (success) or false (failure)

bool rpc_read_file_ex(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, rpc_overlapped overlapped, const char* callback)

ReadFileEx() remote call.

Parameters:

rpcs	RPC server handle
fd	file descriptor
buf	buffer for data
count	number of bytes to be read
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

true (success) or false (failure)

bool rpc_write_file_ex(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, rpc_overlapped overlapped, const char* callback)

WriteFile() remote call.

Parameters:

rpcs	RPC server handle
fd	file descriptor
buf	buffer for data
count	number of bytes to be sent
overlapped	overlapped object or RPC_NULL
callback	completion callback name

Returns:

true (success) or false (failure)

int rpc_overfill_buffers_ex(rcf_rpc_server* rpcs, int sock, uint64_t* sent, bool is_nonblocking)

Overfill the buffers on receive and send sides of TCP connection. If socket is blocking, it will be set non-blocking inside and changed back on return.

Parameters:

rpcs	RPC server
sock	socket for sending
sent	total bytes written to sending socket while both sending and receiving side buffers are overfilled
is_nonblocking	true if socket is in non-blocking mode, false otherwise.

Returns:

-1 in the case of failure or 0 on success

static const char* wsa_name_convert(const char* name)

Convert WSA function name to RPC name

Macros

#define RCF_RPC_MAX_ACCEPT_CONDS

Maximal number of accept conditions

#define RPC_WSA_IOCTL_OUTBUF_MAX

Maximum length of expected result