Typedefs | Functions
Context creation and destruction

Typedefs

typedef void(* tanvastouch_log_cb) (void *data, const char *str)
 

Functions

TANVASTOUCH_API int tanvastouch_open (const char *engine_name, tanvastouch_ctx **p_ctx)
 
TANVASTOUCH_API int tanvastouch_close (tanvastouch_ctx *ctx)
 
TANVASTOUCH_API tanvastouch_log_cb tanvastouch_set_log_cb (tanvastouch_ctx *ctx, tanvastouch_log_cb cb, void *data)
 

Detailed Description

Typedef Documentation

◆ tanvastouch_log_cb

typedef void(* tanvastouch_log_cb) (void *data, const char *str)

The logging callback function type.

Parameters
dataUser data pointer.
strThe log string. This string lives only as long as the callback invocation; if you need it to live longer, you must copy it.

Function Documentation

◆ tanvastouch_close()

TANVASTOUCH_API int tanvastouch_close ( tanvastouch_ctx ctx)

Destroys contexts created by tanvastouch_open.

Parameters
ctxThe context to destroy. The contents of the pointed-to memory should not be read after destruction. If ctx is NULL, this function does nothing.
Returns
TANVASTOUCH_OK. At present, this function does not return any failure codes.

◆ tanvastouch_open()

TANVASTOUCH_API int tanvastouch_open ( const char *  engine_name,
tanvastouch_ctx **  p_ctx 
)

Opens a connection to the TanvasTouch Engine.

This function may be used to either acquire a connection or test that a connection can be made to an engine. To acquire a connection, pass a non-NULL pointer in p_ctx; to test, pass NULL in p_ctx.

You should always call tanvastouch_close on the pointer passed in p_ctx.

Failure codes:

Examples:

Testing for an engine at the default location:

int rc = tanvastouch_open(NULL, NULL, NULL, NULL);
if (rc == TANVASTOUCH_OK) {
handle_connection_ok();
} else {
handle_connection_error(rc);
}

Establishing a connection:

tanvastouch_ctx *ctx = NULL;
int rc = tanvastouch_open(engine_path, &ctx);
if (rc != TANVASTOUCH_OK) {
fprintf(stderr, "error: %s\n", tanvastouch_strerror(rc));
return -1;
}
Parameters
engine_nameThe engine to connect to. May be NULL. On UNIX platforms, this is the path to a UNIX socket. On Windows, this is currently unused. If this is NULL, the default name will be used.
p_ctxIf not null, a pointer will be written to this location. On success, the pointed-to location will contain a pointer to a tanvastouch_ctx object. On failure, the pointed-to location will contain NULL.
Returns
TANVASTOUCH_OK on success, a failure code otherwise.

◆ tanvastouch_set_log_cb()

TANVASTOUCH_API tanvastouch_log_cb tanvastouch_set_log_cb ( tanvastouch_ctx ctx,
tanvastouch_log_cb  cb,
void *  data 
)

Set a logger callback.

Some API operations may produce extra log output as a debugging aid; this callback receives those log messages. The log output is probably not of interest to application users, but it will not contain any sensitive information, so the visibility of the logging output is at your discretion.

Each context has its own logger callback. The default callback is the null pointer, i.e. the callback is disabled.

The context does not take ownership of the user data pointer.

Parameters
ctxThe context to modify.
cbThe callback to assign.
dataUser data pointer.
Returns
A pointer to the old callback.
TANVASTOUCH_OK
#define TANVASTOUCH_OK
Definition: tanvastouch_errors.h:48
tanvastouch_close
TANVASTOUCH_API int tanvastouch_close(tanvastouch_ctx *ctx)
tanvastouch_ctx
struct tanvastouch_ctx tanvastouch_ctx
Definition: tanvastouch.h:157
tanvastouch_open
TANVASTOUCH_API int tanvastouch_open(const char *engine_name, tanvastouch_ctx **p_ctx)
tanvastouch_strerror
const TANVASTOUCH_API char * tanvastouch_strerror(int err)