- Overview
- Files
- Related Pages
- Modules

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

  data | User data pointer.
  str | The 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

  ctx | The 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:

- TANVASTOUCH_ERROR_CLIENT_CANNOT_FIND_ENGINE
- TANVASTOUCH_ERROR_CLIENT_PERMISSION_DENIED
- TANVASTOUCH_ERROR_CLIENT_INCOMPATIBLE

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));
tanvastouch_close(ctx);
return -1;
}

Parameters

  engine_name | The 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_ctx | If 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

  ctx | The context to modify.
  cb | The callback to assign.
  data | User 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)