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

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_callbacks *	eid_vwr_cbstruct ()
	Create the eid_vwr_ui_callbacks struct. More...

DllExport struct eid_vwr_preview *	eid_vwr_get_preview (const EID_CHAR *filename)
	Create a preview for the given file. More...

DllExport void	eid_vwr_poll ()
	Check if there is an event to be handled. More...

DllExport void	eid_vwr_be_mainloop ()
	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

enum 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.

enum 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

enum 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

enum 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

enum 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.

enum eid_vwr_states

Possible states.

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

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_file the file to read

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.

DllExport void eid_vwr_be_mainloop ( )

Loop over eid_vwr_poll().

Returns: never

DllExport void eid_vwr_be_select_slot	(	int	automatic,
		unsigned long	manualslot
	)

Select the current reader.

Parameters

automatic	if nonzero, let the backend decide which reader and ignore the value of manualslot.
manualslot	if automatic is zero, ignore all readers except for the one with this as the slot id.

See also: eid_vwr_ui_callbacks::readers_changed()

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_file the name of the file in which to save data.

See also: eid_vwr_ui_callbacks::newstate()

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)

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.

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.

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.

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

which the language to which to switch

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

cb	the 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.

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

filename the full path to the filename from which to extract the photo

Returns

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

op	the 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.

DllExport void 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.

Files

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation