MINIDRV_TRANSFER_CONTEXT structure (wiamindr_lh.h)
The MINIDRV_TRANSFER_CONTEXT structure is used to store image and other information needed for a memory-callback data transfer or a file data transfer.
Syntax
typedef struct _MINIDRV_TRANSFER_CONTEXT {
LONG lSize;
LONG lWidthInPixels;
LONG lLines;
LONG lDepth;
LONG lXRes;
LONG lYRes;
LONG lCompression;
GUID guidFormatID;
LONG tymed;
LONG_PTR hFile;
LONG cbOffset;
LONG lBufferSize;
LONG lActiveBuffer;
LONG lNumBuffers;
BYTE *pBaseBuffer;
BYTE *pTransferBuffer;
BOOL bTransferDataCB;
BOOL bClassDrvAllocBuf;
LONG_PTR lClientAddress;
IWiaMiniDrvCallBack *pIWiaMiniDrvCallBack;
LONG lImageSize;
LONG lHeaderSize;
LONG lItemSize;
LONG cbWidthInBytes;
LONG lPage;
LONG lCurIfdOffset;
LONG lPrevIfdOffset;
} MINIDRV_TRANSFER_CONTEXT, *PMINIDRV_TRANSFER_CONTEXT;
Members
lSize
Specifies the size in bytes of this MINIDRV_TRANSFER_CONTEXT structure.
lWidthInPixels
Specifies the width in pixels of the current image. The value of this member is derived from the WIA_IPA_PIXELS_PER_LINE common item property.
lLines
Specifies the total number of lines (the number of horizontal rows of pixels) in the current image. The value of this member is derived from the WIA_IPA_NUMBER_OF_LINES common item property.
lDepth
Specifies the color depth value of the current image in bits per pixel. The value of this member is derived from the WIA_IPA_DEPTH common item property.
lXRes
Specifies the current horizontal resolution of the image in pixels per inch. The value of this member is derived from the WIA_IPS_XRES scanner item property.
lYRes
Specifies the current vertical resolution of the image in pixels per inch. The value of this member is derived from the WIA_IPS_YRES scanner item property.
lCompression
Specifies the type of compression used by the device. The value of this member is derived from the WIA_IPA_COMPRESSION common item property.
guidFormatID
Specifies a GUID that indicates the data format for the device. The value of this member is derived from the WIA_IPA_FORMAT common item property.
tymed
Specifies the type of data transfer. The data transfer specified can be either a memory-callback transfer (TYMED_CALLBACK or TYMED_MULTIPAGE_CALLBACK) or file transfer (TYMED_FILE or TYMED_MULTIPAGE_FILE). The value of this member is derived from the WIA_IPA_TYMED common item property.
This member conveys information related to that in the bTransferDataCB member. See Remarks for more information.
hFile
Specifies the handle to the open file used during file transfers. The minidriver should not use this member. See Remarks for more information.
cbOffset
Specifies the current offset in bytes of the next buffer location used during this transfer.
lBufferSize
Specifies the total size of the transfer buffer.
lActiveBuffer
Specifies which buffer is used for the current transfer. The value of this member must be in the range of 1 through lNumBuffers.
lNumBuffers
Specifies the number of buffers available for data transfer. This value can currently be either 1 or 2.
pBaseBuffer
Points to the start of the base transfer buffer.
pTransferBuffer
Points to the start of the current transfer buffer. For a callback transfer in which double buffering is used, this member alternates between the two buffers, pointing to the beginning of the first buffer, and then to the beginning of the second, and so on.
bTransferDataCB
Specifies whether a data transfer is a memory-callback transfer or a file transfer. This member is set to TRUE if the transfer is a memory-callback transfer, and FALSE if the transfer is a file transfer. For file transfers, the WIA service usually provides a callback routine, which enables the application to receive updates from the minidriver about the status of the file transfer. (The WIA service provides a callback routine if the application provides its own callback routine. See IWiaMiniDrvCallback COM Interface for details.) For file transfers, a minidriver should check the value stored in the pIWiaMiniDrvCallBack member. If that member is NULL, the WIA service does not provide a callback routine, so the driver must not attempt to call it. For memory-callback transfers, the WIA service always provides a callback.
This member conveys information related to that in the tymed member. See Remarks for more information.
bClassDrvAllocBuf
Specifies whether the WIA service has allocated the transfer buffer. This value is TRUE if the WIA service allocated the buffer, and FALSE if not. In that case, it is the minidriver's responsibility to allocate the transfer buffer.
lClientAddress
Specifies the address, in the client's address space, of the transfer. The minidriver must not change this value.
pIWiaMiniDrvCallBack
Points to an IWiaMiniDrvCallBack Interface used for data or status callback transfer.
lImageSize
Specifies the size, in bytes, of uncompressed bits in a single page.
lHeaderSize
Specifies the size, in bytes, of image header data in a single page.
lItemSize
Specifies the size, in bytes, of bits and header. This value can be zero if the item size is unknown before acquisition.
cbWidthInBytes
Specifies the size, in bytes, of an image line.
lPage
Specifies the page number of the current page when scanning a multipage TIFF image. Page numbering begins with zero.
lCurIfdOffset
Specifies the image file directory (IFD) offset in the current page of a multipage TIFF image.
lPrevIfdOffset
Specifies the image file directory (IFD) offset in the previous page of a multipage TIFF image.
Remarks
The WIA service sets most of the members of this structure before it calls the minidriver's IWiaMiniDrv::drvAcquireItemData method. If the minidriver calls wiasGetImageInformation, then that function fills in the remaining members of the MINIDRV_TRANSFER_CONTEXT passed to it.
Because the WIA service currently uses only the TYMED_FILE and TYMED_CALLBACK constants, the tymed and bTransferDataCB members store essentially the same information. For file transfers, when bTransferDataCB is set to FALSE, tymed is set to either TYMED_FILE or TYMED_MULTIPAGE_FILE. For memory-callback transfers, when bTransferDataCB is set to TRUE, tymed is set to either TYMED_CALLBACK or TYMED_MULTIPAGE_CALLBACK.
The hFile member is reserved for use solely by the WIA service. Rather than using this member for file transfers, the minidriver should instead write the data to a buffer, and then call wiasWritePageBufToFile to complete the file transfer.
The minidriver obtains values from specific common or scanner item properties to set the members shown in the following table:
| Member | Set by |
|---|---|
| lWidthInPixels | WIA_IPA_PIXELS_PER_LINE |
| lLines | WIA_IPA_NUMBER_OF_LINES |
| lDepth | WIA_IPA_DEPTH |
| lXRes | WIA_IPS_XRES |
| lYRes | WIA_IPS_YRES |
| lCompression | WIA_IPA_COMPRESSION |
| guidFormatID | WIA_IPA_FORMAT |
| tymed | WIA_IPA_TYMED |
Usually, the minidriver sets the preceding structure members directly from the values of the item properties. An application or the minidriver will have set the item properties earlier. The WIA service fills in its service context, using the property values. The driver can use the values stored in this context for quick reference.
The WIA service sets the following structure members:
hFile
bTransferDataCB
bClassDrvAllocBuf
Either the minidriver or the wiasGetImageInformation service library function sets the following structure members:
lImageSize
lHeaderSize
lItemSize
cbWidthInBytes
The following members of this structure are used in data transfer callbacks. The WIA service or the minidriver sets these members. In several cases, the value stored in bClassDrvAllocBuf determines whether the WIA service or the minidriver sets the member.
| Member | Set by |
|---|---|
| cbOffset | Minidriver |
| lBufferSize | WIA service or minidriver. If bClassDrvAllocBuf is TRUE, the WIA service sets this member; otherwise, the minidriver sets it. |
| lActiveBuffer | WIA service. The minidriver must not modify this member. |
| lNumBuffers | WIA service. The minidriver must not modify this member. |
| pBaseBuffer | WIA service or minidriver. If bClassDrvAllocBuf is TRUE, the WIA service sets this member; otherwise, the minidriver sets it. |
| pTransferBuffer | WIA service or minidriver. If bClassDrvAllocBuf is TRUE, the WIA service sets this member; otherwise, the minidriver sets it. |
| lClientAddress | WIA service. The minidriver must not modify this member. |
| pIWiaMiniDrvCallBack | WIA service |
Requirements
| Requirement | Value |
|---|---|
| Header | wiamindr_lh.h (include Wiamindr.h) |
See also
IWiaMiniDrv::drvAcquireItemData