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);
te_bool rpc_duplicate_handle(rcf_rpc_server* rpcs, pid_t src, int old_fd, pid_t tgt, int* new_fd);
te_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);
te_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);
te_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);
te_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);
te_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);
te_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);
te_bool rpc_cancel_io(rcf_rpc_server* rpcs, int fd);
te_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);
te_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);
te_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);
te_bool rpc_close_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent);
te_bool rpc_reset_event(rcf_rpc_server* rpcs, rpc_wsaevent hevent);
te_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);
te_bool rpc_get_wsa_ioctl_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int* bytes, te_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);
te_bool rpc_wsa_get_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, size_t* bytes, te_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, te_bool wait_all, uint32_t timeout, te_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);
te_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);
te_bool rpc_read_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* received, rpc_overlapped overlapped);
te_bool rpc_write_file(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, size_t* sent, rpc_overlapped overlapped);
te_bool rpc_read_file_ex(rcf_rpc_server* rpcs, int fd, void* buf, size_t count, rpc_overlapped overlapped, const char* callback);
te_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, te_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

te_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

te_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()

te_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

te_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()

te_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)

te_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()

te_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.

te_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)

te_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

te_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

te_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

te_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()

te_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()

te_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.

te_bool rpc_get_wsa_ioctl_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, int* bytes, te_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

te_bool rpc_wsa_get_overlapped_result(rcf_rpc_server* rpcs, int s, rpc_overlapped overlapped, size_t* bytes, te_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, te_bool wait_all, uint32_t timeout, te_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()

te_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.

te_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) of FALSE (failure)

te_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) of FALSE (failure)

te_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) of FALSE (failure)

te_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) of FALSE (failure)

int rpc_overfill_buffers_ex(rcf_rpc_server* rpcs, int sock, uint64_t* sent, te_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