Host a gallery file for remote access. More...

Typedefs
typedef struct roc_server_type *	roc_server
	Abstract server handle.

typedef struct roc_amqp_server_type *	roc_amqp_server
	Server handle specific to RabbitMQ deployments.

Functions
roc_error	roc_set_server_credentials (const char private_key, const char certificate)
	Set server SSL/TLS credentials. More...

roc_error	roc_get_ssl_protocols (roc_string *protocols)
	Get SSL/TLS supported protocols. More...

roc_error	roc_set_ssl_protocols (const char *protocol_string)
	Set SSL/TLS supported protocols. More...

roc_error	roc_get_ssl_ciphers (roc_string *ciphers)
	Get SSL/TLS supported ciphers. More...

roc_error	roc_set_ssl_ciphers (const char *cipher_string)
	Set SSL/TLS supported protocols. More...

roc_error	roc_set_server_protocol (bool use_http)
	Define the protocol the server should use. More...

roc_error	roc_start_gallery_server (roc_gallery gallery, int port, roc_server *server)
	Host a gallery file for remote access. More...

roc_error	roc_start_amqp_server (roc_amqp_server server, roc_string location, roc_gallery gallery, const char local_gallery_path, roc_string stream_name, int64_t offset)
	Configure a gallery server to connect with a RabbitMQ Server. More...

roc_error	roc_stop_amqp_server (roc_amqp_server *server)
	Stop a running roc_amqp_server. More...

roc_error	roc_gallery_exec_protobuf (roc_gallery gallery, uint8_t request_data, size_t request_len, roc_buffer response_data, size_t *response_len)
	Execute a ROC Web API ProtoBuf request. More...

roc_error	roc_gallery_server_update (roc_server server, roc_gallery new_gallery, const char *original_gallery_file)
	Replaces the gallery currently being served. More...

roc_error	roc_start_database_server (roc_database database, int port, roc_server *server)
	Host a database for remote access. More...

roc_error	roc_start_template_pipe_server (roc_template_pipe template_pipe, int port, roc_server *server)
	Host a template pipe for remote access. More...

roc_error	roc_start_floating_license_server (int port, roc_server *server)
	Host a floating license server for remote access. More...

roc_error	roc_server_connections (roc_server server, int *connections)
	Obtain the number of clients connected to a server. More...

roc_error	roc_stop_server (roc_server *server)
	Stop a running roc_server. More...

Detailed Description

Host a gallery file for remote access.

Host a roc_gallery for remote access with roc_start_gallery_server. Host a roc_database for remote access with roc_start_database_server. Host a roc_template_pipe for remote access with roc_start_template_pipe_server.

Function Documentation

◆ roc_set_server_credentials()

roc_error roc_set_server_credentials	(	const char *	private_key,
		const char *	certificate
	)

Set server SSL/TLS credentials.

Parameters

[in]	private_key	Path to private key used for encrypted connections. See Certificate Generation.
[in]	certificate	Path to certificate used for encrypted connections. see Certificate Generation.

Remarks: This function is thread-unsafe and should only be called once.

◆ roc_get_ssl_protocols()

roc_error roc_get_ssl_protocols ( roc_string * protocols )

Get SSL/TLS supported protocols.

Obtain a newline-separated list of supported protocols, filtered by roc_set_ssl_protocols if specified.

Free protocols after use with roc_free_string.

Parameters

[out] protocols Supported protocols.

Remarks: This function is reentrant.

See also: roc_set_ssl_protocols

◆ roc_set_ssl_protocols()

roc_error roc_set_ssl_protocols ( const char * protocol_string )

Set SSL/TLS supported protocols.

protocol_string follows OpenSSL's Cipher String Convention. A protocol_string of NULL or empty string (the default) allows all protocols supported by the underlying OpenSSL library.

Examples

Protocol String	Meaning
`TLSv1`	Any TLSv1.x verision (no SSLv3)
`TLSv1.2`	TLSv1.2 only
`TLSv1.2:TLSv1.3`	TLSv1.2 or TLSv1.3 only

Parameters

[in] protocol_string Protocols to support.

Remarks: This function is thread-unsafe.

See also: roc_get_ssl_protocols

◆ roc_get_ssl_ciphers()

roc_error roc_get_ssl_ciphers ( roc_string * ciphers )

Get SSL/TLS supported ciphers.

Obtain a newline-separated list of supported ciphers, filtered by roc_set_ssl_ciphers and/or roc_set_ssl_protocols if specified.

Free ciphers after use with roc_free_string.

Parameters

[out] ciphers Supported ciphers.

Remarks: This function is reentrant.

See also: roc_set_ssl_ciphers

◆ roc_set_ssl_ciphers()

roc_error roc_set_ssl_ciphers ( const char * cipher_string )

Set SSL/TLS supported protocols.

A cipher_string of NULL or empty string (the default) allows all ciphers supported by the underlying OpenSSL library.

Cipher String Convention

The following characters have special meanings:

Character	Meaning
`:`	List separator
`-`	Remove any cipher that contains the following substring

Examples

Cipher String	Meaning
`SHA256:SHA384`	SHA256 or SHA384 ciphers only

Parameters

[in] cipher_string Ciphers to support.

Remarks: This function is thread-unsafe.

See also: roc_get_ssl_ciphers

◆ roc_set_server_protocol()

roc_error roc_set_server_protocol ( bool use_http )

Define the protocol the server should use.

Default is use_http false, meaning data is transfered as size-prefixed FlatBuffers.

Parameters

use_http If true use HTTP protocol, otherwise send raw messages.

Remarks: This function is thread-safe.

◆ roc_start_gallery_server()

roc_error roc_start_gallery_server	(	roc_gallery	gallery,
		int	port,
		roc_server *	server
	)

Host a gallery file for remote access.

The gallery can be accessed remotely by using roc_open_gallery with <hostname>:<port> as the file name, and used in Gallery Construction and Search functions. When serving multiple galleries, each must be assigned to a unique port. Add ?encryption=true after the port number if the server is running SSL/TLS encryption, set by roc_set_server_credentials. Add http:// before the hostname if roc_set_server_protocol.

The gallery is expected to stay valid for at least as long as it is being served.

For encrypted communication call roc_set_server_credentials first. For logging call roc_set_logging first.

Obtain the current active connection count with roc_server_connections. Stop hosting the gallery with roc_stop_server.

This function is exposed in the Command Line Interface as roc-serve.

Example: roc_server server;
roc_gallery gallery = ...;
roc_start_gallery_server(gallery, 6688, &server);

Parameters

[in]	gallery	The gallery to host for remote access.
[in]	port	Port to listen for incomming connections.
[out]	server	Server handle to initialize.

Remarks: This function is reentrant.

◆ roc_start_amqp_server()

roc_error roc_start_amqp_server	(	roc_amqp_server *	server,
		roc_string	location,
		roc_gallery	gallery,
		const char *	local_gallery_path,
		roc_string	stream_name,
		int64_t	offset
	)

Configure a gallery server to connect with a RabbitMQ Server.

The AMQP server location is prefixed with "amqp://", and should be started alongside roc_open_gallery. Messages writing to the roc_gallery such as roc_enroll will be sent/received through the stream_name. When opening a new roc_gallery, set offset to 0.

This function is exposed in the Command Line Interface as roc-amqp-worker.

Close the RabbitMQ connection with roc_stop_amqp_server.

Example: roc_amqp_server rabbitmqServer;
roc_gallery gallery = ...;
roc_start_amqp_server(&rabbitmqServer,
"amqp://username:password@address"),
gallery,
"/local_gallery_directory",
"broadcast-stream-name"),
streamOffset);
// Finished processing
roc_stop_amqp_server(&rabbitmqServer);

Parameters

[out]	server	Server handle to initialize.
[in]	location	Username, password, and address of RabbitMQ Server.
[in]	gallery	Gallery to process requests for.
[in]	local_gallery_path	Path to directory containing roc_gallery.
[in]	stream_name	Name of write-request stream administered by RabbitMQ.
[in]	offset	Offset into write-request stream.

Remarks: This function is reentrant.

◆ roc_stop_amqp_server()

roc_error roc_stop_amqp_server ( roc_amqp_server * server )

Stop a running roc_amqp_server.

Logs this server out of the RabbitMQ connection.

Parameters

[in] server Server to stop.

Remarks: This function is reentrant.

◆ roc_gallery_exec_protobuf()

roc_error roc_gallery_exec_protobuf	(	roc_gallery	gallery,
		uint8_t *	request_data,
		size_t	request_len,
		roc_buffer *	response_data,
		size_t *	response_len
	)

Execute a ROC Web API ProtoBuf request.

Free response_data after use with roc_free_buffer.

Parameters

[in]	gallery	Gallery to execute against.
[in]	request_data	ProtoBuf request bytes.
[in]	request_len	ProtoBuf request size.
[out]	response_data	ProtoBuf response bytes.
[out]	response_len	ProtoBuf response length.

Remarks: This function is thread-safe.

◆ roc_gallery_server_update()

roc_error roc_gallery_server_update	(	roc_server	server,
		roc_gallery	new_gallery,
		const char *	original_gallery_file
	)

Replaces the gallery currently being served.

Existing connections will continue to reference the original gallery. When all existing connections are closed the original gallery is closed with roc_close_gallery and the original_gallery_file is deleted.

Parameters

[in]	server	Server to update.
[in]	new_gallery	Gallery to use for new connections.
[in]	original_gallery_file	Original gallery file to delete.

Remarks: This function is reentrant.

◆ roc_start_database_server()

roc_error roc_start_database_server	(	roc_database	database,
		int	port,
		roc_server *	server
	)

Host a database for remote access.

Analagous to roc_start_gallery_server.

Parameters

[in]	database	The database to host for remote access.
[in]	port	Port to listen for incomming connections.
[out]	server	Server handle to initialize.

Remarks: This function is thread-safe.

◆ roc_start_template_pipe_server()

roc_error roc_start_template_pipe_server	(	roc_template_pipe	template_pipe,
		int	port,
		roc_server *	server
	)

Host a template pipe for remote access.

Analagous to roc_start_gallery_server.

Parameters

[in]	template_pipe	The template pipe to host for remote access.
[in]	port	Port to listen for incomming connections.
[out]	server	Server handle to initialize.

Remarks: This function is thread-safe.

◆ roc_start_floating_license_server()

roc_error roc_start_floating_license_server	(	int	port,
		roc_server *	server
	)

Host a floating license server for remote access.

Parameters

[in]	port	Port to listen for incomming connections.
[out]	server	Server handle to initialize.

Remarks: This function is thread-safe.

◆ roc_server_connections()

roc_error roc_server_connections	(	roc_server	server,
		int *	connections
	)

Obtain the number of clients connected to a server.

Example: roc_server server = ...;
int connections;
roc_server_connections(server, &connections);

Parameters

[in]	server	The server hosting a data structure for remote access.
[out]	connections	Open connection count.

Remarks: This function is thread-safe.

◆ roc_stop_server()

roc_error roc_stop_server ( roc_server * server )

Stop a running roc_server.

Any current connections will no longer be able to access the server. You can check the current connection count with roc_server_connections.

Example: roc_server server = ...;
roc_stop_server(&server);

Parameters

[in] server Server to stop.

Remarks: This function is reentrant.

Typedefs

Functions

Detailed Description

Function Documentation

◆ roc_set_server_credentials()

◆ roc_get_ssl_protocols()

◆ roc_set_ssl_protocols()

◆ roc_get_ssl_ciphers()

◆ roc_set_ssl_ciphers()

Cipher String Convention

◆ roc_set_server_protocol()

◆ roc_start_gallery_server()

◆ roc_start_amqp_server()

◆ roc_stop_amqp_server()

◆ roc_gallery_exec_protobuf()

◆ roc_gallery_server_update()

◆ roc_start_database_server()

◆ roc_start_template_pipe_server()

◆ roc_start_floating_license_server()

◆ roc_server_connections()

◆ roc_stop_server()