eid-viewer
eid-viewer library
Files | Data Structures | Enumerations | Functions
the (base) C API

Files

file  eid-viewer.h
 Main include file.
 
file  oslayer.h
 contains the functions, enums and structures that need to be known by the ui
 

Data Structures

struct  _slotdesc
 
struct  eid_vwr_ui_callbacks
 Callbacks which the backend can perform towards the UI. More...
 
struct  eid_vwr_preview
 

Enumerations

enum  eid_vwr_source { EID_VWR_SRC_NONE, EID_VWR_SRC_FILE, EID_VWR_SRC_CARD, EID_VWR_SRC_UNKNOWN }
 
enum  eid_vwr_loglevel { EID_VWR_LOG_DETAIL = 0, EID_VWR_LOG_NORMAL = 1, EID_VWR_LOG_COARSE = 2, EID_VWR_LOG_ERROR = 3 }
 Log levels. More...
 
enum  eid_vwr_pinops { EID_VWR_PINOP_TEST, EID_VWR_PINOP_CHG }
 
enum  eid_vwr_result { EID_VWR_RES_FAILED, EID_VWR_RES_SUCCESS, EID_VWR_RES_UNKNOWN }
 
enum  eid_vwr_states {
  STATE_LIBOPEN, STATE_CALLBACKS, STATE_READY, STATE_TOKEN,
  STATE_TOKEN_WAIT, STATE_TOKEN_ID, STATE_TOKEN_CERTS, STATE_TOKEN_PINOP,
  STATE_TOKEN_SERIALIZE, STATE_TOKEN_ERROR, STATE_FILE, STATE_FILE_READING,
  STATE_FILE_WAIT, STATE_CARD_INVALID, STATE_NO_TOKEN, STATE_NO_READER
}
 Possible states. More...
 
enum  eid_vwr_langs {
  EID_VWR_LANG_NONE, EID_VWR_LANG_DE, EID_VWR_LANG_EN, EID_VWR_LANG_FR,
  EID_VWR_LANG_NL
}
 

Functions

DllExport void eid_vwr_pinop (enum eid_vwr_pinops op)
 Perform a PIN operation. More...
 
DllExport int eid_vwr_createcallbacks (struct eid_vwr_ui_callbacks *cb)
 Initialize the callbacks. More...
 
DllExport struct eid_vwr_ui_callbackseid_vwr_cbstruct ()
 Create the eid_vwr_ui_callbacks struct. More...
 
DllExport struct eid_vwr_previeweid_vwr_get_preview (const EID_CHAR *filename)
 Create a preview for the given file. More...
 
DllExport int eid_vwr_poll ()
 Check if there is an event to be handled. More...
 
void * eid_vwr_be_mainloop (void *val)
 Loop over eid_vwr_poll(). More...
 
DllExport void eid_vwr_be_serialize (const EID_CHAR *target_file)
 Save the currently-open data. More...
 
DllExport void eid_vwr_be_deserialize (const EID_CHAR *source_file)
 Open a file. More...
 
DllExport const char * eid_vwr_be_get_xmlform ()
 Get the currently-open data in XML form. More...
 
DllExport void eid_vwr_be_select_slot (int automatic, unsigned long manualslot)
 Select the current reader. More...
 
DllExport void eid_vwr_be_set_invalid ()
 Mark the current data as invalid. More...
 
DllExport void eid_vwr_close_file ()
 Close the current file. More...
 
DllExport void eid_vwr_convert_set_lang (enum eid_vwr_langs which)
 Set the backend language. More...
 
DllExport enum eid_vwr_langs eid_vwr_convert_get_lang ()
 Return the backend language. More...
 

Detailed Description

Enumeration Type Documentation

◆ eid_vwr_langs

Possible languages.

Enumerator
EID_VWR_LANG_NONE 

No language has yet been selected. Used as initializer.

EID_VWR_LANG_DE 

German.

EID_VWR_LANG_EN 

English.

EID_VWR_LANG_FR 

French.

EID_VWR_LANG_NL 

Dutch.

◆ eid_vwr_loglevel

Log levels.

These are the log levels which the backend may use.

Enumerator
EID_VWR_LOG_DETAIL 

most detail

EID_VWR_LOG_NORMAL 

intermediate detail

EID_VWR_LOG_COARSE 

least detail

EID_VWR_LOG_ERROR 

error message; a dialog box with the message (in addition to adding to the log) may be appropriate

◆ eid_vwr_pinops

PIN operations. TEST: perform a login (and return whether the login was successful). CHG: change PIN

Enumerator
EID_VWR_PINOP_TEST 

perform a login and return whether the login was successful

EID_VWR_PINOP_CHG 

change the PIN code of the card

◆ eid_vwr_result

Result of an operation.

Enumerator
EID_VWR_RES_FAILED 

operation failed

EID_VWR_RES_SUCCESS 

the operation returned successfully

EID_VWR_RES_UNKNOWN 

the operation did not finish

◆ eid_vwr_source

Types of data sources we can have

Enumerator
EID_VWR_SRC_NONE 

No source. UI should be cleared.

EID_VWR_SRC_FILE 

File source. "Print", "Validate" and "Close" operations should be allowed, PIN-related operations are impossible. Save is pointless (but may be possible).

EID_VWR_SRC_CARD 

Card source. Close should not be allowed, everything else should be.

EID_VWR_SRC_UNKNOWN 

Unknown. Used as initializer.

◆ eid_vwr_states

Possible states.

be-statemach-docs.png
Enumerator
STATE_LIBOPEN 

The library has been opened. Used as an initializer.

STATE_CALLBACKS 

The callbacks have been defined.

STATE_READY 

Ready to receive a token (eID card)

STATE_TOKEN 

A token (eID card) has been found.

STATE_TOKEN_WAIT 

The card has been read, we're now waiting for events to do something else.

STATE_TOKEN_ID 

Reading identity data.

STATE_TOKEN_CERTS 

Reading certificates.

STATE_TOKEN_PINOP 

Performing a PIN operation.

STATE_TOKEN_SERIALIZE 

Saving data to a file.

STATE_TOKEN_ERROR 

An error occurred while dealing with the card.

STATE_FILE 

We're dealing with files.

STATE_FILE_READING 

We're reading from the file currently.

STATE_FILE_WAIT 

We finished parsing the file.

STATE_CARD_INVALID 

The data was determined to be invalid. That is, the card could be read, but signature validation failed.

STATE_NO_TOKEN 

We don't have a card, and we also don't have a file.

STATE_NO_READER 

We don't have a reader (yet?)

Function Documentation

◆ eid_vwr_be_deserialize()

DllExport void eid_vwr_be_deserialize ( const EID_CHAR *  source_file)

Open a file.

Returns before the file has been opened; reading the file and parsing it is done in a background thread. The immediate effect of calling this function is a state transition to STATE_FILE. If a read or parser error occurs, the state reverts to STATE_NO_TOKEN.

Parameters
source_filethe file to read

◆ eid_vwr_be_get_xmlform()

DllExport const char* eid_vwr_be_get_xmlform ( )

Get the currently-open data in XML form.

This method can be called when the state machine is in one of the STATE_FILE or STATE_TOKEN_WAIT states.

Returns
a pointer to the XML-encoded data of the most recently opened card data, or NULL if the state machine is not currently in the right state.
Note
this data is owned by the eid-viewer library and should not be freed by the caller.

◆ eid_vwr_be_mainloop()

void* eid_vwr_be_mainloop ( void *  val)

Loop over eid_vwr_poll().

Returns
never

◆ eid_vwr_be_select_slot()

DllExport void eid_vwr_be_select_slot ( int  automatic,
unsigned long  manualslot 
)

Select the current reader.

Parameters
automaticif nonzero, let the backend decide which reader and ignore the value of manualslot.
manualslotif automatic is zero, ignore all readers except for the one with this as the slot id.
See also
eid_vwr_ui_callbacks::readers_changed()

◆ eid_vwr_be_serialize()

DllExport void eid_vwr_be_serialize ( const EID_CHAR *  target_file)

Save the currently-open data.

Returns before the save operation has finished. The state machine will switch to the STATE_TOKEN_SERIALIZE state while data is being saved, and will revert to STATE_TOKEN_WAIT when the operation has finished, or to STATE_TOKEN_ERROR if an error occurs.

Parameters
target_filethe name of the file in which to save data.
See also
eid_vwr_ui_callbacks::newstate()

◆ eid_vwr_be_set_invalid()

DllExport void eid_vwr_be_set_invalid ( )

Mark the current data as invalid.

If the UI detects that the card data is invalid for some reason, then this method will move the state machine to the STATE_CARD_INVALID state. The backend will not perform this operation by itself.

This method is only valid if the state machine is currently in STATE_TOKEN or one of its child states.

See also
  • eid_vwr_verify_cert() tests whether the certificate chains up to a known root certificate, and is not revoked
  • eid_vwr_check_data_validity() tests whether the data on the card is signed by the given RRN certificate (but does not check the RRN certificate itself)

◆ eid_vwr_cbstruct()

DllExport struct eid_vwr_ui_callbacks* eid_vwr_cbstruct ( )

Create the eid_vwr_ui_callbacks struct.

While it is possible, in theory, to create the struct by malloc()ing it manually, doing so will fail when the eid-viewer library is updated and a new callback function is added. For this reason, applications that want to continue working with future versions of the library without compatibility issues must use this function to allocate a correctly-sized structure.

Returns
an allocated eid_vwr_ui_callbacks struct, with all members set to NULL.

◆ eid_vwr_close_file()

DllExport void eid_vwr_close_file ( )

Close the current file.

If the current state is STATE_FILE, switch to STATE_NO_TOKEN. In all other cases, does nothing.

◆ eid_vwr_convert_get_lang()

DllExport enum eid_vwr_langs eid_vwr_convert_get_lang ( )

Return the backend language.

Returns
the current backend language as previously set by eid_vwr_convert_set_lang(). If no language has previously been set, returns EID_VWR_LANG_NONE.

◆ eid_vwr_convert_set_lang()

DllExport void eid_vwr_convert_set_lang ( enum eid_vwr_langs  which)

Set the backend language.

This method sets the current backend language to the given language. If any data has been loaded (i.e., the state machine is in state STATE_FILE or STATE_TOKEN_WAIT), this will also re-issue eid_vwr_ui_callbacks::newstringdata() events for which the representation in the new language may be different.

Parameters
whichthe language to which to switch

◆ eid_vwr_createcallbacks()

DllExport int eid_vwr_createcallbacks ( struct eid_vwr_ui_callbacks cb)

Initialize the callbacks.

Must be called by every application which wants to make use of this API, otherwise nothing will happen.

Parameters
cbthe callback functions which this application implements
Returns
0 if the callbacks were installed successfully.
Note
the API assumes that this function is called exactly once for the lifetime of the application. While it should be safe to call it more than once, this is not very well tested and therefore doing so is not recommended.

◆ eid_vwr_get_preview()

DllExport struct eid_vwr_preview* eid_vwr_get_preview ( const EID_CHAR *  filename)

Create a preview for the given file.

This function simply parses the XML file and extracts the embedded JPEG photo. It is useful for an "open file" dialog, or similar.

Parameters
filenamethe full path to the filename from which to extract the photo
Returns

◆ eid_vwr_pinop()

DllExport void eid_vwr_pinop ( enum eid_vwr_pinops  op)

Perform a PIN operation.

If the state machine is currently in the TOKEN_WAIT state, issue a PIN operation. In all other cases, does nothing.

Parameters
opthe operation to perform; EID_VWR_PINOP_TEST to log on as a test to see if the PIN code is valid, or EID_VWR_PINOP_CHG to change the PIN code.

◆ eid_vwr_poll()

DllExport int eid_vwr_poll ( )

Check if there is an event to be handled.

Will handle one event and then return. Useful if an event loop exists elsewhere; otherwise, using eid_vwr_be_mainloop() is recommended. returns zero on succes, non-zero when reader list could not be formed or when no UI callback has been set