Interface for receiving captured samples and other events. More...

#include <SignDocSDK-c.h>

Public Types
typedef int(*	SIGNDOC_UserCaptureListener_gotSample) (void *aClosure, int aX, int aY, int aP, int aT)
	Callback implementing SIGNDOC_CaptureListener_gotSample(): A sample has been received from the capture device. More...

typedef int(*	SIGNDOC_UserCaptureListener_gotSamples) (void aClosure, const struct SIGNDOC_SignatureSample aSamples, int aCount)
	Callback implementing SIGNDOC_CaptureListener_gotSamples(): Multiple samples have been received from the capture device. More...

typedef int(*	SIGNDOC_UserCaptureListener_gotEvent) (void *aClosure, int aEvent, int aButtonId)
	Callback implementing SIGNDOC_CaptureListener_gotEvent(): got an event. More...

typedef void(*	SIGNDOC_UserCaptureListener_gotError) (void aClosure, int aEncoding, const char aMessage)
	Callback implementing SIGNDOC_CaptureListener_gotError(): got an error. More...

Public Member Functions
int	SIGNDOC_CaptureListener_gotSample (struct SIGNDOC_CaptureListener *aObj, int aX, int aY, int aP, int aT)
	A sample has been received from the capture device. More...

int	SIGNDOC_CaptureListener_gotSamples (struct SIGNDOC_CaptureListener aObj, const struct SIGNDOC_SignatureSample aSamples, int aCount)
	Multiple samples have been received from the capture device. More...

int	SIGNDOC_CaptureListener_gotEvent (struct SIGNDOC_CaptureListener *aObj, int aEvent, int aButtonId)
	Got an event. More...

void	SIGNDOC_CaptureListener_gotError (struct SIGNDOC_CaptureListener aObj, int aEncoding, const char aMessage)
	Got an error. More...

void	SIGNDOC_CaptureListener_delete (struct SIGNDOC_CaptureListener *aObj)
	SIGNDOC_CaptureListener destructor. More...

void *	SIGNDOC_CaptureListener_getUserPointer (const struct SIGNDOC_CaptureListener *aObj, int aKey)
	Get the pointer set with SIGNDOC_CaptureListener_setUserPointer(). More...

void	SIGNDOC_CaptureListener_setUserPointer (struct SIGNDOC_CaptureListener aObj, int aKey, void aPointer)
	Store a pointer in the SIGNDOC_CaptureListener object. More...

struct SIGNDOC_CaptureListener *	SIGNDOC_UserCaptureListener_new (struct SIGNDOC_Exception *aEx, void aClosure, SIGNDOC_UserCaptureListener_gotSample aGotSample, SIGNDOC_UserCaptureListener_gotSamples aGotSamples, SIGNDOC_UserCaptureListener_gotEvent aGotEvent, SIGNDOC_UserCaptureListener_gotError aGotError, void aReserved1, void aReserved2)
	SIGNDOC_UserCaptureListener constructor. More...

Detailed Description

Interface for receiving captured samples and other events.

Member Typedef Documentation

typedef void( * SIGNDOC_UserCaptureListener_gotError) (void *aClosure, int aEncoding, const char *aMessage)

Callback implementing SIGNDOC_CaptureListener_gotError(): got an error.

SignDoc SDK currently does not call this function for a user-provided listener, but you can call this function from your own implementation of SIGNDOC_UserCaptureDevice and SIGNDOC_UserCaptureDisplay to report an error.

SIGNDOC_Capture_waitCapture2() will return with SIGNDOC_CaptureResult_getEvent() returning SIGNDOC_CAPTURERESULT_EVENT_ERROR, SIGNDOC_Capture_waitCapture() will return with mEvent of SIGNDOC_CaptureOutput set to SIGNDOC_CAPTUREOUTPUT_EVENT_ERROR.

Parameters

[in]	aClosure	The pointer (to the user-defined object) passed to SIGNDOC_UserCaptureListener_new().
[in]	aEncoding	The encoding of aMessage (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aMessage	The error message.

typedef int( * SIGNDOC_UserCaptureListener_gotEvent) (void *aClosure, int aEvent, int aButtonId)

Callback implementing SIGNDOC_CaptureListener_gotEvent(): got an event.

Implement this function to handle some button events without terminating capture.

Parameters

[in]	aClosure	The pointer (to the user-defined object) passed to SIGNDOC_UserCaptureListener_new().
[in]	aEvent	The event to be returned by SIGNDOC_CaptureResult_getEvent() or by SIGNDOC_Capture_waitCapture() in mEvent of SIGNDOC_CaptureOutput: SIGNDOC_CAPTURERESULT_EVENT_TIMEOUT, SIGNDOC_CAPTURERESULT_EVENT_VIRTUAL_BUTTON, SIGNDOC_CAPTURERESULT_EVENT_HARDWARE_BUTTON, SIGNDOC_CAPTURERESULT_EVENT_CALLBACK, SIGNDOC_CAPTURERESULT_EVENT_UI_BUTTON, or SIGNDOC_CAPTURERESULT_EVENT_CLOSED (which are identical to SIGNDOC_CAPTUREOUTPUT_EVENT_TIMEOUT, SIGNDOC_CAPTUREOUTPUT_EVENT_VIRTUAL_BUTTON, SIGNDOC_CAPTUREOUTPUT_EVENT_HARDWARE_BUTTON, SIGNDOC_CAPTUREOUTPUT_EVENT_CALLBACK, SIGNDOC_CAPTUREOUTPUT_EVENT_UI_BUTTON, and SIGNDOC_CAPTUREOUTPUT_EVENT_CLOSED).
[in]	aButtonId	The button identifier to be returned by SIGNDOC_CaptureResult_getButtonId() or by SIGNDOC_Capture_waitCapture() in mButtonId of SIGNDOC_CaptureOutput.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_CONTINUE, SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, or SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE. All return values but SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE terminate capture.

typedef int( * SIGNDOC_UserCaptureListener_gotSample) (void *aClosure, int aX, int aY, int aP, int aT)

Callback implementing SIGNDOC_CaptureListener_gotSample(): A sample has been received from the capture device.

Implement this function to receive samples one by one.

If you implement both SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples(), the former will be called for a single sample, the latter will be called for multiple samples received en bloc.

If you implement only one of SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples(), only the one you override will be called.

SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples() are not called for samples that contribute to potential virtual button clicks unless boolean parameter "ReportAllSamples" of SIGNDOC_CaptureParameters is set to SIGNDOC_TRUE.

This function may be called from an arbitrary thread.

Parameters

[in]	aClosure	The pointer (to the user-defined object) passed to SIGNDOC_UserCaptureListener_new().
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[in]	aP	Pressure (or force), normalized to 0 through 1023. A sample with zero pressure is used for separating strokes.
[in]	aT	Relative time in milliseconds, -1 if the capture device does not have a time channel.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_CONTINUE, SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, or SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE.

See also: SIGNDOC_UserCaptureListener_gotSamples()

typedef int( * SIGNDOC_UserCaptureListener_gotSamples) (void *aClosure, const struct SIGNDOC_SignatureSample *aSamples, int aCount)

Callback implementing SIGNDOC_CaptureListener_gotSamples(): Multiple samples have been received from the capture device.

If you implement both SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples(), the former will be called for a single sample, the latter will be called for multiple samples received en bloc.

If you implement only one of SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples(), only the one you override will be called.

If you intend to return SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE or SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, you should use the SIGNDOC_UsercaptureListener_getSample() callback rather than this one as the return value of this callback applies to all samples pointed to by aSamples.

SIGNDOC_UserCaptureListener_gotSample() and SIGNDOC_UserCaptureListener_gotSamples() are not called for samples that contribute to potential virtual button clicks unless boolean parameter "ReportAllSamples" of SIGNDOC_CaptureParameters is set to SIGNDOC_TRUE.

This function may be called from an arbitrary thread.

Parameters

[in]	aClosure	The pointer (to the user-defined object) passed to SIGNDOC_UserCaptureListener_new().
[in]	aSamples	A pointer to an array of SIGNDOc_SignatureSample objects.
[in]	aCount	Number of SIGNDOC_SignatureSample objects pointed to be aSamples. Always positive.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_CONTINUE, SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, or SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE.

See also: SIGNDOC_UserCaptureListener_gotSample()

Member Function Documentation

void SIGNDOC_CaptureListener_delete ( struct SIGNDOC_CaptureListener * aObj )

SIGNDOC_CaptureListener destructor.

Parameters

[in] aObj A pointer to the SIGNDOC_CaptureListener object.

void * SIGNDOC_CaptureListener_getUserPointer	(	const struct SIGNDOC_CaptureListener *	aObj,
		int	aKey
	)

Get the pointer set with SIGNDOC_CaptureListener_setUserPointer().

Typically, that pointer is used for implementing a language binding.

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aKey	A value identifying the pointer. Values 0 through 255 are reserved for SignDoc SDK.

Returns: The pointer set with SIGNDOC_CaptureListener_setUserPointer(), NULL if SIGNDOC_CaptureListener_setUserPointer() has not been called or if aKey does not match the value most recently passed SIGNDOC_CaptureListener_setUserPointer().

void SIGNDOC_CaptureListener_gotError	(	struct SIGNDOC_CaptureListener *	aObj,
		int	aEncoding,
		const char *	aMessage
	)

Got an error.

SignDoc SDK currently does not call this function for a user-provided listener, but you can call this function from your own implementation of SIGNDOC_UserCaptureDevice and SIGNDOC_UserCaptureDisplay to report an error.

SIGNDOC_Capture_waitCapture2() will return with SIGNDOC_CaptureResult_getEvent) returning SIGNDOC_CAPTURERESULT_EVENT_ERROR, SIGNDOC_Capture_waitCapture() will return with mEvent of SIGNDOC_CaptureOutput set to SIGNDOC_CAPTUREOUTPUT_EVENT_ERROR. The error message will be returned by SIGNDOC_CaptureResult_getCaptureError() SIGNDOC_CaptureResult_getCaptureErrorW(), SIGNDOC_Capture_getCaptureError(), and SIGNDOC_Capture_getCaptureErrorW().

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aEncoding	The encoding of aMessage (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aMessage	The error message.

See also: SIGNDOC_CaptureListener_gotEvent()

int SIGNDOC_CaptureListener_gotEvent	(	struct SIGNDOC_CaptureListener *	aObj,
		int	aEvent,
		int	aButtonId
	)

Got an event.

This function may be called from an arbitrary thread.

You can call this function from your own implementation of SIGNDOC_UserCaptureDevice to make SIGNDOC_Capture_waitCapture2() or SIGNDOC_Capture_waitcapture() return. Calling this function for the listener passed to SIGNDOC_CaptureDevice_startCapture() is equivalent to calling SIGNDOC_Capture_stopCapture().

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aEvent	The event to be returned by SIGNDOC_CaptureResult_getEvent() or by SIGNDOC_Capture_waitCapture() in mEvent of SIGNDOC_CaptureOutput: SIGNDOC_CAPTURERESULT_EVENT_TIMEOUT, SIGNDOC_CAPTURERESULT_EVENT_VIRTUAL_BUTTON, SIGNDOC_CAPTURERESULT_EVENT_HARDWARE_BUTTON, SIGNDOC_CAPTURERESULT_EVENT_CALLBACK, SIGNDOC_CAPTURERESULT_EVENT_UI_BUTTON, or SIGNDOC_CAPTURERESULT_EVENT_CLOSED (which are identical to SIGNDOC_CAPTUREOUTPUT_EVENT_TIMEOUT, SIGNDOC_CAPTUREOUTPUT_EVENT_VIRTUAL_BUTTON, SIGNDOC_CAPTUREOUTPUT_EVENT_HARDWARE_BUTTON, SIGNDOC_CAPTUREOUTPUT_EVENT_CALLBACK, SIGNDOC_CAPTUREOUTPUT_EVENT_UI_BUTTON, or SIGNDOC_CAPTUREOUTPUT_EVENT_CLOSED). Use SIGNDOC_CaptureListener_gotError() instead of SIGNDOC_CaptureListener_gotEvent() for SIGNDOC_CAPTURERESULT_EVENT_ERROR (which is identical to SIGNDOC_CAPTUREOUTPUT_EVENT_ERROR).
[in]	aButtonId	The button identifier to be returned by SIGNDOC_CaptureResult_getButtonId() or by SIGNDOC_Capture_waitCapture() in mButtonId of SIGNDOC_CaptureOutput.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_END.

See also: SIGNDOC_CaptureListener_gotError()

int SIGNDOC_CaptureListener_gotSample	(	struct SIGNDOC_CaptureListener *	aObj,
		int	aX,
		int	aY,
		int	aP,
		int	aT
	)

A sample has been received from the capture device.

This function may be called from an arbitrary thread.

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aX	X coordinate.
[in]	aY	Y coordinate.
[in]	aP	Pressure (or force), normalized to 0 through 1023. A sample with zero pressure is used for separating strokes.
[in]	aT	Relative time in milliseconds, -1 if the capture device does not have a time channel.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_CONTINUE, SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, or SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE.

See also: SIGNDOC_CaptureListener_gotSamples()

int SIGNDOC_CaptureListener_gotSamples	(	struct SIGNDOC_CaptureListener *	aObj,
		const struct SIGNDOC_SignatureSample *	aSamples,
		int	aCount
	)

Multiple samples have been received from the capture device.

This function may be called from an arbitrary thread.

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aSamples	A pointer to an array of SIGNDOC_SignatureSample objects.
[in]	aCount	Number of SIGNDOC_SignatureSample objects pointed to be aSamples. Always positive.

Returns: SIGNDOC_CAPTURELISTENER_RETURNVALUE_CONTINUE, SIGNDOC_CAPTURELISTENER_RETURNVALUE_END, or SIGNDOC_CAPTURELISTENER_RETURNVALUE_IGNORE.

See also: SIGNDOC_CaptureListener_gotSample()

void SIGNDOC_CaptureListener_setUserPointer	(	struct SIGNDOC_CaptureListener *	aObj,
		int	aKey,
		void *	aPointer
	)

Store a pointer in the SIGNDOC_CaptureListener object.

Typically, that pointer is used for implementing a language binding. Only one pointer can be stored. This function overwrites the key and pointer set by any prior call.

Parameters

[in]	aObj	A pointer to the SIGNDOC_CaptureListener object.
[in]	aKey	A value identifying the pointer. Values 0 through 255 are reserved for SignDoc SDK.
[in]	aPointer	The pointer to be returned by SIGNDOC_CaptureListener_getUserPointer() for aKey.

struct SIGNDOC_CaptureListener * SIGNDOC_UserCaptureListener_new	(	struct SIGNDOC_Exception **	aEx,
		void *	aClosure,
		SIGNDOC_UserCaptureListener_gotSample	aGotSample,
		SIGNDOC_UserCaptureListener_gotSamples	aGotSamples,
		SIGNDOC_UserCaptureListener_gotEvent	aGotEvent,
		SIGNDOC_UserCaptureListener_gotError	aGotError,
		void *	aReserved1,
		void *	aReserved2
	)

SIGNDOC_UserCaptureListener constructor.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aClosure	A pointer to the user-defined object that will be passed to the callbacks.
[in]	aGotSample	Pointer to function implementing SIGNDOC_CaptureListener_gotSample(). Can be NULL to use the default implementation (which does nothing).
[in]	aGotSamples	Pointer to function implementing SIGNDOC_Capture_gotSamples(). Can be NULL to use the default implementation (which does nothing).
[in]	aGotEvent	Pointer to function implementing SIGNDOC_Capture_gotEvent(). Can be NULL to use the default implementation (which does nothing).
[in]	aGotError	Pointer to function implementing SIGNDOC_Capture_gotError(). Can be NULL to use the default implementation (which does nothing).
[in]	aReserved1	Reserved for future expansion, must be NULL.
[in]	aReserved2	Reserved for future expansion, must be NULL.

Returns: A pointer to a new SIGNDOC_CaptureListener object.

See also: SIGNDOC_CaptureListener_delete()

The documentation for this class was generated from the following file:

SignDocSDK-c.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Member Function Documentation