Functions
CSIRO_WORKSPACEWEB_API int	server_init (int logLevel)

CSIRO_WORKSPACEWEB_API int	server_listen_for_connection (const char *host, int port, NewConnectionCallback callback)

CSIRO_WORKSPACEWEB_API int	server_listen_for_connection_and_wait (const char *host, int port, NewConnectionCallback callback)

CSIRO_WORKSPACEWEB_API int	server_poll (int timeoutMs)

CSIRO_WORKSPACEWEB_API int	server_start_event_loop (EventLoopStartedCallback callback)

CSIRO_WORKSPACEWEB_API int	server_stop_event_loop ()

Detailed Description

Functions for interacting with the application's server, such as polling and listening for new client connections.

Function Documentation

◆ server_init()

CSIRO_WORKSPACEWEB_API int server_init ( int logLevel )

Returns: true if the server was able to be initialised successfully.

◆ server_listen_for_connection()

CSIRO_WORKSPACEWEB_API int server_listen_for_connection	(	const char *	host,
		int	port,
		NewConnectionCallback	callback
	)

Parameters

host	The host (or IP) to listen for new connections on. The server will only accept connections on this host.
port	The port to listen on. The server will only accept connections on this port.
callback	When a new connection is received, this callback will be invoked and the connection details will be provided to it, including a WorkspaceId struct, containing the details of the peer host and port.

Returns: true if the server commences listening for new connections, false if some error occurred.

Listen for a new connection from a client workspace process. In this version of the function, the server will start listening in a separate thread and this function will immediately return. The listening thread will terminate as soon as a new connection is made, after which the specified callback function is invoked. A WorkspaceId struct is provided to the callback function, providing details of the connecting process' hostname and port.

See also: server_listen_for_connection_and_wait

◆ server_listen_for_connection_and_wait()

CSIRO_WORKSPACEWEB_API int server_listen_for_connection_and_wait	(	const char *	host,
		int	port,
		NewConnectionCallback	callback
	)

Parameters

host	The host (or IP) to listen for new connections on. The server will only accept connections on this host.
port	The port to listen on. The server will only accept connections on this port.
callback	When a new connection is received, this callback will be invoked and the connection details will be provided to it, including a WorkspaceId struct, containing the details of the peer host and port.

Returns: true if the server commences listening for new connections, false if some error occurred.

Listen for a new connection from a client workspace process. In this version of the function, the server will listen synchronously, blocking the current thread until a new connection is made. Once a new connection is made, the specified callback function is invoked. A WorkspaceId struct is provided to the callback function, providing details of the connecting process' hostname and port.

Note: This function should only be used in applications where there is no event loop, or the event loop is external to this library. It should especially not be used in GUI applications, as it will make the main thread unresponsive while waiting for connections.

See also: server_listen_for_connection

◆ server_poll()

CSIRO_WORKSPACEWEB_API int server_poll ( int timeoutMs )

Returns: true if the poll request was sent successfully, false otherwise.

Polls the server for any messages from client workspace processes. Messages include updates to watches, errors that have occurred, or success / failed notifications. In the case that messages have been received, previously registered callbacks will be invoked.

See also: workspace_watch; workspace_list_global_names; workspace_list_inputs; workspace_list_outputs; workspace_register_func_error; workspace_register_func_success; workspace_register_func_failed

◆ server_start_event_loop()

CSIRO_WORKSPACEWEB_API int server_start_event_loop ( EventLoopStartedCallback callback )

Parameters

callback The callback function to invoke once the event loop has started successfully.

Returns: true if the event loop starts successfully, false otherwise. True will also be returned if the event loop is already running.

Starts the event loop for the server. The event loop will continually poll for any updates to client workspace processes, and if currently listening, will respond to any new connections that have occurred.

Note: The event loop is not necessarily required in order to use the workspaceweb interface. Alternatively, server_listen_for_connection_and_wait can be used to wait for new connections, and server_poll can be used to periodically check for updates to client workspace processes. This alternative approach is useful for scenarios where an event loop already exists externally to the workspaceweb interface, or no event loop is required.

See also: server_listen_for_connection; server_listen_for_connection_and_wait; server_poll

◆ server_stop_event_loop()

CSIRO_WORKSPACEWEB_API int server_stop_event_loop ( )

Returns: true if the event loop was able to be stopped successfully, false otherwise. False will also be returned if the event loop was not running at the time that this function was called.

Stops the event loop. If the event loop is not running, false will be returned.