Remote Vehicle Interaction library. More...

#include <stddef.h>

Typedefs
typedef void *	TRviHandle

typedef void(*	TRviCallback) (int fd, void serviceData, const char parameters)

Enumerations
enum	ERviStatus { RVI_OK = 0, RVI_ERR_OPENSSL = 100, RVI_ERR_NOCONFIG = 1001, RVI_ERR_JSON = 1002, RVI_ERR_SERVCERT = 1003, RVI_ERR_CLIENTCERT = 1004, RVI_ERR_NORCVCERT = 1005, RVI_ERR_STREAMEND = 1006, RVI_ERR_NOCRED = 1007, RVI_ERR_NOCMD = 1008, RVI_ERR_RIGHTS = 1009, RVI_ERR_JSON_PART = 1010 }

Functions
TRviHandle	rviInit (char *configFilename)
	Initialize the RVI library. Call before using any other functions. More...

int	rviCleanup (TRviHandle handle)
	Tear down the API. More...

int	rviConnect (TRviHandle handle, const char addr, const char port)
	Connect to a remote node at a specified address and port. More...

int	rviDisconnect (TRviHandle handle, int fd)
	Disconnect from a remote node with a specified file descriptor. More...

int	rviGetConnections (TRviHandle handle, int conn, int connSize)
	Return all file descriptors in the RVI context. More...

int	rviRegisterService (TRviHandle handle, const char serviceName, TRviCallback callback, void serviceData)
	Register a service with a callback function. More...

int	rviUnregisterService (TRviHandle handle, const char *serviceName)
	Unregister a previously registered service. More...

int	rviGetServices (TRviHandle handle, char *result, int len)
	Get list of services available. More...

int	rviInvokeService (TRviHandle handle, const char serviceName, const char parameters)
	Invoke a remote service. More...

int	rviProcessInput (TRviHandle handle, int *fdArr, int fdLen)
	Handle input on remote connection(s). More...

Detailed Description

Remote Vehicle Interaction library.

This file is responsible for exposing all available function prototypes and data types for the RVI library.

This is an initial prototype of the RVI library in C and is subject to change. The intended use is to allow a calling application to connect to remote RVI nodes, discover services, register additional services, and invoke remote services.

The RVI library depends on the following libraries:

C standard library: https://www-s.acm.illinois.edu/webmonkeys/book/c_guide/index.html

libJWT: https://github.com/benmcollins/libjwt/

Jansson: http://www.digip.org/jansson/

OpenSSL: https://www.openssl.org/

The RVI library does not currently use the following, but may include it for future interopability with RVI Core nodes:

mpack: http://ludocode.github.io/mpack/

Author: Tatiana Jamison <tjami.nosp@m.son@.nosp@m.jagua.nosp@m.rlan.nosp@m.drove.nosp@m.r.co.nosp@m.m>

Typedef Documentation

typedef void(* TRviCallback) (int fd, void *serviceData, const char *parameters)

Function signature for RVI callback functions

typedef void* TRviHandle

Application handle used to interact with RVI

Enumeration Type Documentation

enum ERviStatus

Function return status codes

Enumerator
RVI_OK	Success
RVI_ERR_OPENSSL	Unhandled error from OpenSSL
RVI_ERR_NOCONFIG	Configuration error
RVI_ERR_JSON	Error in JSON
RVI_ERR_SERVCERT	Server certificate is missing
RVI_ERR_CLIENTCERT	Client certificate is missing
RVI_ERR_NORCVCERT	Client did not receive server cert
RVI_ERR_STREAMEND	Stream end encountered unexpectedly
RVI_ERR_NOCRED	No credentials
RVI_ERR_NOCMD	No (known) command
RVI_ERR_RIGHTS	No right for that operation
RVI_ERR_JSON_PART	Partial JSON

Function Documentation

int rviCleanup ( TRviHandle handle )

Tear down the API.

Calling applications are expected to call this to cleanly tear down the API. This will disconnect from all active connections and free memory allocated by the library.

Parameters

handle - The handle for the RVI context to clean up.

Returns: 0 on success, error code otherwise.

int rviConnect	(	TRviHandle	handle,
		const char *	addr,
		const char *	port
	)

Connect to a remote node at a specified address and port.

This function will attempt to connect to a remote node at the specified addr and port. It will spawn a new connection and block until all handshake and RVI negotiations are complete. On success, it will return the file descriptor for the new socket. On failure, it will return a negative error value.

New services may become immediately available upon connecting to a remote node. To discover the services that are currently available, use the rviGetServices() function. Services may be invoked via rviInvokeService() using the fully-qualified service name.

This operation will block until all TLS read/write operations are complete.

Parameters

handle	- The handle to the RVI context.
addr	- The address of the remote connection.
port	- The target port for the connection. This can be a numeric value or a string such as "http." Allowed values (inherited from OpenSSL) are http, telnet, socks, https, ssl, ftp, and gopher.

Returns: File descriptor on success, negative error value otherwise.

int rviDisconnect	(	TRviHandle	handle,
		int	fd
	)

Disconnect from a remote node with a specified file descriptor.

Parameters

handle	- The handle to the RVI context.
fd	- The file descriptor for the connection to terminate.

Returns: 0 on success, error code otherwise.

int rviGetConnections	(	TRviHandle	handle,
		int *	conn,
		int *	connSize
	)

Return all file descriptors in the RVI context.

Parameters

handle	- The handle to the RVI context.
conn	- Pointer to a buffer to store file descriptors (small integers) for each remote RVI node.
connSize	- Pointer to size of 'conn' buffer. This should be initialized to the size of the conn buffer. On success, it will be updated with the number of file descriptors returned.

This function will fill the conn buffer with active file descriptors from the RVI context and update connSize to indicate the final size.

This operation is entirely local.

Returns: 0 on success, error code otherwise.

int rviGetServices	(	TRviHandle	handle,
		char **	result,
		int *	len
	)

Get list of services available.

This function fills the buffer at result with pointers to strings, up to the value indicated by len. Memory for each string is dynamically allocated by the library and must be freed by the calling application. Before returning, len is updated with the actual number of strings.

This operation is entirely local.

Parameters

handle	- The handle to the RVI context.
result	- A pointer to a block of pointers for storing strings
len	- The maximum number of pointers allocated in result

Returns: 0 on success, error code otherwise.

TRviHandle rviInit ( char * configFilename )

Initialize the RVI library. Call before using any other functions.

The name of a JSON configuration file must be supplied. Example config:

 {
  "dev": {
      "key":  "./priv/clientkey.pem",
      "cert": "./priv/clientcert.pem",
      "id":   "genivi.org/client/bbfbb478-d628-480a-8528-cff40d73678f"
  },
  "ca": {
      "cert": "./priv/cacert.pem",
      "dir":  "./priv/"
  },
  "creddir": "./priv/"
 }

Notably, the device ID should be a unique ID generated from an external source, e.g., util-linux's uuidgen or Microsoft's guidgen.exe.

The ID format is "domain/device-type/uuid".

Parameters

configFilename - Path to the file containing RVI config options.

Returns: A handle for the API on success, NULL otherwise.

int rviInvokeService	(	TRviHandle	handle,
		const char *	serviceName,
		const char *	parameters
	)

Invoke a remote service.

The service name must be the fully-qualified service name (as returned by, e.g., rviGetServices()). The service may be passed parameters in the form of a JSON object containing key-value pairs. Parameters are optional.

Introspection of RVI services is not supported as of the 0.5.0 release, so refer to the documentation on the services you intend to invoke to determine which parameters (if any) to pass.

This will send the RVI command over TLS to the remote node. The operation will block until all SSL read/write operations are complete.

Parameters

handle	- The handle to the RVI context.
serviceName	- The fully-qualified service name to invoke
parameters	- A JSON structure containing the named parameter pairs

Returns: 0 on success, error code otherwise.

int rviProcessInput	(	TRviHandle	handle,
		int *	fdArr,
		int	fdLen
	)

Handle input on remote connection(s).

This function will read data from each of the file descriptors in fdArr (up to fdLen elements long). The calling application must ensure that fdArr is populated only with read-ready descriptors (returned by, e.g., (e)poll() or select()).

This operation will read one message from each file descriptor provided. The calling application should poll using a level trigger, since multiple messages may be pending on a single connection.

This is a blocking operation. If any descriptor in fdArr is not read-ready, the operation will block until data becomes available to read on the descriptor.

Parameters

handle	- The handle to the RVI context.
fdArr	- An array of file descriptors with read operations pending
fdLen	- The length of the file descriptor array

Returns: 0 on success, error code otherwise.

int rviRegisterService	(	TRviHandle	handle,
		const char *	serviceName,
		TRviCallback	callback,
		void *	serviceData
	)

Register a service with a callback function.

This function makes services available to remote RVI nodes that are currently connected to this node. The service may be a fully-qualified service-name or a relative service name. If the service name is not prefixed with this node's identifier (as specified in the configuration file), it will automatically be added.

This will also notify all remote nodes that can invoke the service, based on credentials presented to this node. The operation will block until all SSL read/write operations are complete.

Parameters

handle	- The handle to the RVI context.
serviceName	- The service name to register
callback	- The callback function to be executed upon service invocation.
serviceData	- Parameters to be passed to the callback function (in addition to any JSON parameters from the remote node)

Returns: 0 on success, error code otherwise.

int rviUnregisterService	(	TRviHandle	handle,
		const char *	serviceName
	)

Unregister a previously registered service.

This function unregisters a service that was previously registered by the calling application. If serviceName does not exist, or was registered by a remote node, it does nothing and returns an error code.

This will also notify all remote nodes that could have invoked the service, based on credentials presented to this node. The operation will block until all SSL read/write operations are complete.

Parameters

handle	- The handle to the RVI context
serviceName	The fully-qualified service name to deregister

Returns: 0 on success, error code otherwise.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation