Function Reference¶

Setup¶

ebv_initialize¶

int workspace_id = ebv_intialize("vendorid", "licensekey");

Parameter:

Vendor id (const char*)
License key (const char*)

Return Values:

Success if workspace id greater zero; else the initialization failed
if the return value is below zero:
-1 Empty vendor id not allowed
-2 Empty license key not allowed
-3 vendor id contains characters which may be problematic in XML: < > & " '
-4 the license key is invalid

Initializes a workspace for a single XML document. The returned integer acts as a handle to this specific workspace.

ebv_release¶

int rc = ebv_release(workspace_id);

Parameter:

Workspace id (int)

Return Values:

EBVBXA_OK - release successful
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

The counterpart of ebv_initializes. Releases the obtained memory and other OS specific handles.

Utility¶

ebv_get_errors¶

const char* buffer;
int rc = ebv_get_errors(workspace_id, &buffer);

Parameter:

Workspace id (int)
Errors (const char**)

Return Values:

EBVBXA_OK – errors successfully retrieved
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

This function returns a list of errors issued by the xml parser, if ebv_get_xml returned an error code.

ebv_get_version() / ebv_get_full_version()¶

Parameter: None

Return Values:

version (const char*)

Retrieve the version string for the EBV-BXA. The full version includes branch and commit hash for precise identification of the EBV-BXA build in use.

ebv_log_stdout¶

Parameter:

level (int) - see enum LogLevel in bxa_interface.h

Return Values:

EBVBXA_OK - logfile created successfully

Initializes logger which writes to stdout. E.g., for usage in cluster environments.

ebv_log_file¶

Parameter:

filename (const char*)
append (bool) - append to existing file or create/truncate a file
level (int) - see enum LogLevel in bxa_interface.h

Return Values:

EBVBXA_OK - logfile created successfully
EBVBXA_ERROR - an error occurred while trying to open the file

Creates a log file and logs the full version of the EBV-BXA.

All non EBVBXA_OK return values from the functions of the EBV-BXA will emit a message on log level error. On level debug all calls to EBV functions will be logged with their parameters and return values.

Caution

Log Level trace logs complete XML / fieldlists created/loaded by the EBV functions. This produces large log files fast.

ebv_get_document_type¶

Parameter:

workspace id (int)
buffer (const char**) - pointer to zero terminated buffer with the document type

Return Values:

EBVBXA_OK – document type obtained successfully
EBVBXA_ERROR – document type unknown (invalid/non-EBV XML document or no XML at all in the workspace)
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

Returns the document type in the provided workspace.

Warning

The memory which contains the output is managed by the EBV-BXA. The next call affecting this workspace will invalidate its contents.

Load/Modify XML¶

ebv_load¶

Parameter:

workspace id (int)
filename (const char*)

Return Values:

EBVBXA_OK – XML file loaded successfully
EBVBXA_ERROR - an error occurred while trying to open the file
EBVBXA_FILE_NOT_FOUND - the provided file was not found
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

Loads the XML file into the workspace identified by the provided workspace id. This method is intended for changing the contents of the XML.

Note

This function is non-validating, so invalid XML documents will just load without an error. Whatsoever, this function must be used, if the document contains digital signatures, as a validating parser will normalize(change) loaded XML documents, which automatically breaks digital signatures. It will detect only violations of well-formedness.

ebv_load_bytes¶

Parameter:

workspace id (int)
buffer (const char*)
size (size_t)

Return Values:

EBVBXA_OK – XML file loaded successfully
EBVBXA_ERROR - the loaded XML document is not well formed
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

Loads the XML from a memory block into the workspace identified by the provided workspace id. This method is intended for changing the contents of the XML.

Note

This function is non-validating, so invalid XML documents will just load without an error. Whatsoever, this function must be used, if the document contains digital signatures, as a validating parser will normalize(change) loaded XML documents, which automatically breaks digital signatures. It will detect only violations of well-formedness.

Danger

The memory block must contain UTF-8 encoded XML and must persist until the function returned, else undefined behavior will occur.

ebv_load_bytes_validating¶

Parameter:

workspace id (int)
buffer (const char*)
size (size_t)

Return Values:

EBVBXA_OK – XML file loaded successfully
EBVBXA_ERROR - the loaded XML document is not well formed
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.

Loads the XML from a memory block into the workspace identified by the provided workspace id. This function is validating, invalid XML documents will lead to an error. This method is intended for read-only operations.

Warning

This function has the side effect of changing the XML implicitly by a process called normalization in the XML standard. This will break digital signatures in the document, because signatures guarantee that the signed content is unchanged. This happens unnoticed and will manifest the moment the XML is serialized again.

Danger

The memory block must contain UTF-8 encoded XML and must persist until the function returned, else undefined behavior will occur.

ebv_load_template¶

Parameter:

workspace id (int)
filename (const char*)

Return Values:

EBVBXA_OK – XML file loaded successfully
EBVBXA_ERROR - an error occurred while trying to open the file
EBVBXA_FILE_NOT_FOUND - the provided file was not found
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was previously released.
EBVBXA_LAYER_SIGNED a signed document can’t be a template

Creates another document from a template XML file. Internally, the loaded document gets new ids, so that it is a unique document with the same content as the original.

ebv_load_template_bytes¶

Parameter:

workspace id (int)
buffer (const char*)
size (size_t)

Return Values:

EBVBXA_OK – XML file loaded successfully
EBVBXA_ERROR - the loaded xml document is not well formed.
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.
EBVBXA_LAYER_SIGNED a signed document can’t be a template

Creates another document from a template XML contained in a memory block. Internally, the loaded document gets new ids, so that it is a unique document with the same content as the original.

ebv_create¶

Parameter:

workspace id (int)
document type (const char*)

Return Values:

EBVBXA_OK – document created successfully
EBVBXA_ERROR - the document type is unknown
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Creates a new document of the provided type. It consists of a single empty layer.

Allowed document types are (see also bxa_interface.h, DT_xxx constants):

ANZEIGE
DECKBLATT
LIEFERSCHEIN
TRAEGERDOKUMENT

ebv_add_layer¶

Parameter:

workspace id (int)
layer type (const char*)

Return Values:

EBVBXA_OK– layer created successfully
EBVBXA_ERROR - the layer type is unknown or not allowed. This relates to the order of layers, or the corresponding document types.
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Adds a new layer to the document which encapsulates all previous layers.

Allowed layer types are (see also bxa_interface.h, LT_xxx constants):

LieferscheinLayer (only for document type LIEFERSCHEIN)
DeckblattLayer (only for document type DECKBLATT)
VoranzeigeLayer (only for document type ANZEIGE, and only if the previous layer is a VoranzeigeLayer)
AbschlussanzeigeLayer (only for document type ANZEIGE)

ebv_get_field_list¶

const char* buffer;
size_t size;
int rc = get_ebv_field_list(workspace_id, 0, true, &buffer, &size, true);

Parameter:

workspace id (int)
layer number (int) - zero addresses the current layer (newest), other layers following in chronological order (to the oldest)
view (bool) - true means the projection of all layers from the provided layer number, or false only the distinct layer content
buffer (const char**) - receiving the pointer the buffer containing the fieldlist
length (size_t*) - receiving the number of bytes in the buffer
includeMeta (bool) - controls if the field list also contains detailed information about layer, signatures and attachments.

Return Values:

EBVBXA_OK – Field list extracted successfully
EBVBXA_ERROR - The loaded XML document is not well formed.
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Extracts the Information from the xml and provides a flat list.

Warning

The memory block which contains the output is managed by the EBV-BXA. The next call affecting this workspace will invalidate its contents.

ebv_set_field_list¶

Parameter:

workspace id (int)
buffer (const char*)
size (size_t)

Return Values:

EBVBXA_OK – Field list set successfully
EBVBXA_ERROR - The loaded XML document is not well formed.
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.
EBVBXA_LAYER_SIGNED - The top layer is signed, no changes allowed.

Provides the content that will be written to the top layer of the XML document.

In contrast to the content ebv_get_field_list delivers, the following information must be omitted:

A leading plus/minus/space is not allowed. This is a read only information. Every entry in the list will be written to the top layer.
Meta-fields are read only, too. Meta information will be changed by methods of the interface.
Fields with empty values should only be included if deletion of their content is intended, else don’t put the entry into the list.

ebv_get_xml¶

Parameter:

workspace id (int)
buffer (const char**) - pointer to zero terminated buffer to the XML

Return Values:

EBVBXA_OK – XML successfully created
EBVBXA_ERROR - XML could not be created. Call ebv_get_errors for details.
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

This gets the current xml from the library utf-8 encoded.

Warning

The memory block which contains the output is managed by the EBV-BXA. The next call affecting this workspace will invalidate its contents.

Binary Attachments¶

ebv_add_attachment_file¶

const char* uuid;
int rc = ebv_add_attachment_file(workspace_id, "my.pdf", AT_SONSTIGE, "a remark", &uuid);

Parameter:

workspace id (int)
filename (const char*)
type (const char*)
remark (const char*)
uuid (const char**)

Return Values:

EBVBXA_OK – attachment added successfully
EBVBXA_FILE_NOT_FOUND - the provided file was not found
EBVBXA_LAYER_SIGNED The top layer is signed, attaching not allowed
EBVBXA_INVALID_ENDCODING remark contains invalid utf8 characters
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Adds the content of the file to the XML as binary attachment. If the method returns EBV_BXA_OK, uuid contains the UUID for the corresponding attachment.

Type can be one of (see also bxa_interface.h, AT_xxx constants):

Sonstiges (all document types)
Nachweis (DECKBLATT, ANZEIGE)
Lageskizze (DECKBLATT, ANZEIGE)

Warning

The memory block which contains the uuid is managed by the EBV-BXA. The next call affecting this workspace will invalidate its contents.

ebv_add_attachment¶

const char* uuid;
int rc = ebv_add_attachment(workspace_id, buffer, size, AT_NACHWEIS, "a remark", &uuid);

Parameter:

workspace id (int)
buffer (const char*)
length (std::size)
type (const char*)
remark (const char*)
uuid (const char**)

Return Values:

EBVBXA_OK – attachment added successfully
EBVBXA_LAYER_SIGNED The top layer is signed, attaching not allowed
EBVBXA_INVALID_ENDCODING remark contains invalid UTF-8 characters
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Adds the content of the memory block provided by buffer and length to the XML as binary attachment. For further details see ebv_add_attachment_file.

Warning

The memory block which contains the uuid is managed by the EBV-BXA. The next call affecting this workspace will invalidate its contents.

ebv_remove_attachment¶

int rc = ebv_add_attachment(workspace_id, uuid);

Parameter:

workspace id (int)
uuid (const char*)

Return Values:

EBVBXA_OK – attachment removed successfully
EBVBXA_ERROR – removing the attachment raised an unexpected exception
EBVBXA_OUT_OF_RANGE – uuid is unknown or an older layer contains the attachment
EBVBXA_LAYER_SIGNED - Attachment found in top layer is signed, removing is not allowed
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Removes the attachment identified by the uuid. By design it is only allowed to change the top layer.

ebv_export_attachment¶

const char* buffer;
size_t size;
int rc = ebv_export_attachment(workspace_id,  uuid, &buffer, &size);

Parameter:

workspace id (int)
uuid (const char*)
buffer (const char**)
length (size_t*)

Return Values:

EBVBXA_OK – attachment removed successfully
EBVBXA_OUT_OF_RANGE – there is no attachment with the provided uuid
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Gets the content of the attachment identified by the uuid. The content will be written to a memory block managed by the EBV-BXA. It is only available until the next call of an EBV-BXA function.

ebv_change_attachment_remark¶

int rc = ebv_change_attachment_remark(workspace_id, uuid, "changed remark text");

Parameter:

workspace id (int)
uuid (const char*)
remark (const char*)

Return Values:

EBVBXA_OK – attachment remark changed successfully
EBVBXA_OUT_OF_RANGE – there is no attachment with the provided uuid
EBVBXA_LAYER_SIGNED - Attachment found in top layer is signed, changing the remark is not allowed
EBVBXA_UNKNOWN_ID - The workspace id is unknown or was released.

Changes the corresponding remark.