ANNO_open

- open an annotation connection

SYNOPSIS

#include <$OV_HEADER/ecs/ANNO/ANNO.h>

int32 ANNO_open (
ESOK_ConnectionId conId,
const char *circuitName,
const char *annotateNodeName,
ANNO_ConnectionId *annoId );

DESCRIPTION

This function opens a connection between the caller and a specified correlation engine to receive specified annotation requests.

Annotation connections can be opened to a single correlation engine or to multiple correlation engines. A new annotation connection ID is set by each call of ANNO_open.

As part of the open operation, an annotate request filter can be specified. The filter limits the annotate requests received to those that match the circuit name and/or the Annotate node name specified.

Neither, one, or both of the circuitName and annotateNodeNameparameters can be specified. If neither parameter is specified then all annotation requests are received.

Parameters

ESOK_ConnectionId conId

Connection identifier that identifies an open socket stack connection (as set by a call to ESOK_open). This parameter identifies the target correlation engine.

const char *circuitName

The name of the circuit from which annotation requests are received. May be zero in which case annotation requests are received from all circuits. The name is the name given to the circuit when loaded into the engine, not the circuit file name. It is case sensitive.

const char *annotateNodeName

Name of the annotation node to receive annotation requests from. May be zero in which case annotation requests are received from all Annotate nodes. The name is the short node name, not the fully scoped name.

ANNO_ConnectionId *annoId

Address of the annotation connection ID that identifies this connection in subsequent calls to this annotation stack. This value is returned by this function.

RETURNS

ECS_SUCCESS

Succeeded.

ANNO_NOT_INITIALISED

ANNO_stackInit has not been called.

ANNO_BAD_CONNECTION

The specified annotation connection is not open.

ESOK_RESOURCE_LIMIT

No more socket stack connections available.

ESOK_COMMUNICATION_ERROR

The engine isn't running or can't be communicated with.