QPx_AcqRunSession
| QPx_AcqRunSession(acqProtocol; acqProtocol; acqProtocol; acqProtocol):error | |||
|---|---|---|---|
 |
acqProtocol | Longint | Acquisition protocol ID |
|
deviceName | Text | Device name |
|
sessionOptions | Longint | Acquisition options |
|
eventHandler | Text | Event handler method name |
 |
error | Longint | Error result |
Run an acquisition session
This command runs an acquisition session. The caller is notified about saved images through a callback event handler method.
Parameter acqProtocol specifies the protocol to be used in the acquisition session. It can be one of the acquisition protocol ID constants:
| qpx_AcqTWAINProtocol | 1 | TWAIN identifier |
| qpx_AcqPictureTransferProtocol | 2 | Picture Transfer Protocol identifier |
| qpx_AcqVideoProtocol | 4 | Video acquisition protocol identifier |
| qpx_AcqICScannerProtocol | 8 | Mac OS Image Capture Scanner protocol identifier |
Parameter deviceName specifies the device to be used in the acquisition session. To get all device names for a specific protocol, use the QPx_AcqGetDeviceList command. Alternatively, the QPx_AcqSelectDevice command can be used to let the user select the acquisition protocol and device.
The sessionOptions parameter can be used to specify acquisition options. It can be a bitwise "OR" combination of the following constants:
| qpx_AcqGetMultiple | 0x00000001 | Acquire multiple images (if supported). |
| qpx_AcqHideDeviceGUI | 0x00000200 | Hide the device acquisition GUI (if supported). |
| qpx_AcqTWAINEnableADF | 0x00010000 | Enable the use of the Automatic Document Feeder on TWAIN scanners (if supported). This option and qpx_AcqTWAINEnableTPU are mutually exclusive. |
| qpx_AcqTWAINEnableTPU | 0x00100000 | Enable the use of the Automatic Document Feeder on TWAIN scanners (if supported). This option and qpx_AcqTWAINEnableADF are mutually exclusive. |
| qpx_AcqTWAINEnableDuplex | 0x00020000 | Enable duplex scanning with TWAIN scanners (if supported). This option is valid only when qpx_AcqTWAINEnableADF is also specified. |
| qpx_AcqPTPAllFileTypes | 0x00200000 | Enable acquisition of all file types (images, video, audio) from PTP cameras. Mac only. |
| qpx_AcqPTPDeleteAfter | 0x00040000 | Delete the image on the PTP digital camera after acquisition (if supported). |
NOTE Not all protocols and devices support multi-image acquisition:
- PTP and Video devices support acquisition of multiple images.
- TWAIN devices may support it or not; it depends on device kind and driver implementation. Drivers for scanners with Automatic Document Feeders, slide scanners and digital cameras, as well as scanner drivers that allow selection of scanning regions are likely to support multi-image acquisition.
- If the device does not support multi-image acquisition, this command acquires a single image and returns.
NOTE Not all protocols and devices support acquisition with the device dialog hidden:
- Acquisition dialogs that are implemented by QPix (Picture Transfer Protocol and Video) can be hidden.
- According to the TWAIN specification this capability is highly recommended. However, because it is not mandatory, not all manufacturers implement this option in their TWAIN drivers.
- If the qpx_AcqHideDeviceGUI option is specified and the device cannot hide its GUI, this command runs the acquisition session with the device dialog visible.
Default location of files: acquired images are saved in the 4D datafile folder when running under single-user 4D, and in the application folder when running under 4D Client. Call QPx_AcqSetImageFolder to change the location.
The event handler method
While the acquisition session is running, QPix calls the method specified by eventHandler passing information about important events, such as saving an image. The event handler method must comply with the following calling interface:
| Syntax of the event handler method | |||
|---|---|---|---|
|
$1 - eventKindParam | Longint | The kind of the event |
|
$2 - acqProtocolParam | Longint | The acquisition protocol identifier |
|
$3 - deviceNameParam | Text | The name of the device |
|
$4 - eventInfoParam | Pointer | Pointer to extra data specific to the event |
|
$0 - errorCode | Longint | Error code |
Parameter eventKindParam receives the kind of the event. This is one of the following constants:
| qpx_AcqImageSaved | 0x1003 | An image was saved on disk. Parameter eventInfoParam points to a text variable that contains the full pathname to the saved image file. Supported by all acquisition protocols. |
| qpx_AcqImageDeleted | 0x1004 | An image was deleted on the device (typically a digital camera). Parameter eventInfoParam points to a text variable that contains the name of the image. Supported by the PTP acquisition protocol. |
| qpx_AcqSetupWindowBounds | 0x2001 | The device dialog is about to be displayed and QPix asks the application for the dialog's bounds. Parameter eventInfoParam points to a longint array with 4 elements. The event handler method can set the array elements to the left, top, right, and bottom coordinates of the desired window bounds. Supported by the PTP (Mac OS) and Video acquisition protocols. |
| qpx_AcqSetupWindowTitle | 0x2002 | The device dialog is about to be displayed and QPix asks the application for the dialog's title. Parameter eventInfoParam points to a string. The event handler method can set the string to the desired window title. Supported by the PTP (Mac OS) and Video acquisition protocols. |
| qpx_AcqSetupResolution | 0x3001 | The acquisition session is about to begin and QPix asks the application for the image resolution. Parameter eventInfoParam points to a longint array with 2 elements that contains the current horizontal and vertical resolution of the device. The event handler method can change the contents of the array to the desired horizontal and vertical resolution. Supported by the TWAIN (GUI-less) and Video acquisition protocols. |
| qpx_AcqSetupPixelFormat | 0x3002 | The acquisition session is about to begin and QPix asks the application for the pixel format. Parameter eventInfoParam points to a longint that contains the current pixel format of the device. The event handler method can change the longint to the desired pixel format. Acceptable pixel formats are 1 for black and white, 40 for gray scale, 8 for palette color, and 24 for true color. Not all pixel formats are supported by all devices. QPix will adjust the requested pixel format to match the closest pixel format that the device can handle. Supported by the TWAIN (GUI-less) acquisition protocol. |
| qpx_AcqRestoreDeviceSettings | 0x4001 | QPix asks the application for saved device settings.Parameter eventInfoParam points to a BLOB that contains the settings for the device. The event handler method can assign to the BLOB the device settings that were previously stored during a qpx_AcqStoreDeviceSettings acquisition event. Note that QuickTime and/or the video digitizer component (VDIG) may reject or adjust some of all of the device settings. Supported by the Video acquisition protocol on Mac OS. |
| qpx_AcqStoreDeviceSettings | 0x4002 | QPix passes to the application the device settings. Parameter eventInfoParam points to a BLOB that contains the settings for the device. The event handler method can store the BLOB to be later passed to the device during a qpx_AcqRestoreDeviceSettings acquisition event. Supported by the Video acquisition protocol on Mac OS. |
Parameter acqProtocolParam receives the ID of the acquisition protocol being used.
Parameter deviceNameParam receives the name of the device being used.
Parameter eventInfoParam receives a pointer to information specific to the kind of the event. The interpretation and usage of this parameter is described in the event kind table above.
The event handler returns an error code. This error code indicates to QPix if the handler executed successfully, if an error has occured, or if the event handler was not interested in handling the event.
- If event was handled successfully, the handler must return qpx_noErr (zero).
- If there was an error handling the event, a suitable error code must be returned (non zero).
- If the handler did not handle the event, it must return error qpx_eventNotHandledErr.
It is very important for the event handler method to follow the last rule for events it is not interested in. This lets QPix distinguish between an event that was not handled from one that was handled successfully, and also allows for future expansion by introducing new kinds of event.
Important note: The event handler method should do as little as possible, because it is called in a constrained environment with lots of things (alien to 4D) happening at the same time.
Use the event handler method for operations such as:
- Gathering the pathnames of acquired images in a process array.
- Moving the acquired images to another location.
- Sending messages to other 4D processes.
Avoid using the event handler method for operations such as:
- Opening new windows.
- Doing heavy database I/O.
Related commands
| QPx_AcqGetDeviceList | Get all devices available to an acquisition protocol |
| QPx_AcqSelectDevice | Display the device selection dialog for an acquisition protocol |
| QPx_AcqSetImageFolder | Specify the storage location of acquired images |