SPTabletServer

The Kofax TabletServer is a module which accepts tablet capture commands as a service and redirects the commands to the addressed devices.

All SignWare objects that create a tablet need some initialization to address the TabletServer rather than the tablet hardware. You will thus have to use a tablet create method that passes the tablet class and tablet options.

Initialisation

• Tablet class must be "SPTabletTabletServer"
• Tablet Options, must be located in section "[TABLETSERVER]"
  • ServerAddress: URI of the tablet server
  • TerminalId: unique Identifyer of the tablet (terminal), required
  • ServerTimeout: timeout to connect to the server in mseconds, default 250
  • SSLConfigurationFile: File that contains the SSLConfiguration parameters, see SSLConfiguration
  • SSLConfiguration: xml description of the SSL-configuration parameters

Note: Configuration options are read in this order:

• from the passed pszOptions String
• [only Windows]: from the registry, HKLM\Software\SOFTPRO\Pads\TabletServer
• from the file "tablet.ini", the typical file location methods apply

The TabletServer returns a description of the device capabilities, once connected. Please evaluate the capabilities such as tablet Lcd etc.

Some capabilities need special consideration:

• SPTabletGetTabletType SP_TABLET_NO_REALTIME_VECTORS: the device buffers all vector data until a hardware or a virtual button was pressed or a timeout occured.
  The application GUI should not display an erase or an OK button, as the application cannot display the actually entered signature.

TabletServer devices may use hardware buttons (rather than virtual buttons) to pass button actions to the application. The application must therefor evaluate hardware buttons when the active driver is a TabletServer-Driver.
Hardware button id's (see Tablet Hardware button Assignment).

• 0: OK button
• 1: Cancel button
• 2: Erase button
• 3: shutter button

TabletServer devices add some special features:

• Total timeout: define the maximum time to capture a signature, SPAquireSetIntProperty("AcquireTimeout", time[mSecs]), SPGuiAquSetIntProperty("AcquireTimeout", time[mSecs]), SPTabletSetTabletOption("AcquireTimeout", time[mSecs])
  set AcquireTimeout to 0 to use maximum time, 999999 [mSecs]
  The timeout will send a notification to the application StatusChanged(0x401, SP_TIMEOUTERR)
• Watchdog timeout: define a maximum time to send a callback notification to the application, SPAquireSetIntProperty("AcquireWatchdog", time[mSecs]),SPGuiAquSetIntProperty("AcquireWatchdog", time[mSecs]), the callback is StatusChanged(1, SP_INTERR)
  set AcquireWatchdog to 0 to disable the watchdog
  Note: The AcquireWatchdog timeout must be greater that the AcquireTimeout!
• Idle timeout: define the maximum time after the last pen stroke to send a timeout, SPAcquireSetTimeout, SPGuiAcquSetTimeout, SPTabletSetTabletOption("IdleTimeout", time[msecs])
  set IdleTimeout to 0 to to use maximum idle time, 999999 [mSecs]
  The timeout will send a notification to the application StatusChanged(0x401, SP_TIMEOUTERR)
• Foreground color and background color may be set with SPAcquireSetIntProperty("ForegroundColor|BackgroundColor", color), SPGuiAcquSetIntProperty("ForegroundColor|BackgroundColor", color) and SPTabletSetTabletOption("ForegroundColor|BackgroundColor", color)
• Pen thickness may be set with SPAcquireSetIntProperty("PenThickness", width), SPGuiAcquSetIntProperty("PenThickness", width), SPTabletSetTabletOption("PenThickness", width)
• Virtual buttons are passed from SPAcquire and SPGuiAcqu using the according xml descriptors

TabletServer timeouts
A total of four timeouts must be considered:

• Connection timeout: a connection timeout is considered a hard error. The application will be invoked with a return code SP_INVALIDERR in synchronous calls (SPAcquireConnect, SPGuiAcquConnect) or with a status callback with iMajor set to 1 and iDetail set to SP_INVALIDERR.
• Watchdog timeout: a watchdog timeout is considered a hard error. The application will be invoked through the status callback (SPAcquireSetStatusListener, SPGuiAcquSetStatusListener) with iMajor set to 1 and iDetail set to SP_INTERR.
• Idle timeout: the idle timeout will be invoked xx mseconds after the last stroke. The notification calls the timout listener (SPAcquireSetTimeout, SPGuiAcquSetTimeout)
• Total timeout: the total timeout will be invoked xx mseconds after the a call to start a signature capture (SPAcquireAcquireStart, SPGuiAcquAcquireStart). The notification calls the timout listener if a timeout listener is set (SPAcquireSetTimeout, SPGuiAcquSetTimeout), or the status callback with iMajor set to 0x401 and iDetail set to SP_TIMEOUT_ERR

Most notifications from the tablet server are passed as callbacks to the registered StatusChange listener. Applications which use TabletServer must register StatusChange listeners and evaluate the status notifications.
StatusCallback depending on the Major parameter:

• 1: an error occured, depending on iDetail:
  • SP_CANCELERR: the operation was cancelled
    if iDetail is SP_INVALIDERR then a recoverable error occured, the application may reconnect to the tablet and restart aquiry
  • SP_INTERR: watchdog timeout
  • any other value indicates an error and should end aquiry mode
• 0x401: TabletServer specific message, depending on iDetail:
  • SP_TIMEOUTERR: the operation timed out, a valid signature may be available. The application should finally stop acquiry mode.

Note:

The application cannot stop a capture process once started, the application must wait for the device response, it has either terminated capture mode or timed out or an error occured. The device will no longer be accessible if the application fails to do so (e. g. if the application aborts an operation on a watchdog timeout).