SendRecvBidiDataFromPort function
The SendRecvBidiDataFromPort function, which can be implemented in either a language monitor server DLL or a port monitor server DLL, supports bidirectional communication between an application and a printer or print server.
Syntax
DWORD SendRecvBidiDataFromPort(
HANDLE hPort,
DWORD dwAccessBit,
LPCWSTR pAction,
PBIDI_REQUEST_CONTAINER pReqData,
PBIDI_RESPONSE_CONTAINER *ppResData
);
Parameters
hPort
Specifies a caller-supplied port handle.dwAccessBit
Caller-supplied ACCESS_MASK structure (defined in the Microsoft Windows SDK documentation) containing the access granted to the user during a call to the spooler's OpenPrinter function. For more information about ACCESS_MASK and OpenPrinter, see the Windows SDK documentation.pAction
Pointer to a caller-supplied Unicode string that contains the requested action. The value of this parameter should be one of the BIDI_ACTION_XXX constants described in the Windows SDK documentation.pReqData
Pointer to a BIDI_REQUEST_CONTAINER structure that contains the bidi request data.ppResData
Pointer to a memory location that will receive the address of a BIDI_RESPONSE_CONTAINER structure that contains the bidi response.
Return value
If the operation succeeds, the SendRecvBidiDataFromPort function returns ERROR_SUCCESS. Otherwise, it returns a Win32 error code.
Remarks
Language and port monitors optionally can define a SendRecvBidiDataFromPort function and include the function's address in the pfnSendRecvBidiDataFromPort member of a Windows XP MONITOR2 structure.
The function's hPort parameter receives the port handle supplied by the monitor's OpenPort or OpenPortEx function.
Typically, a language monitor's SendRecvBidiDataFromPort function calls the associated port monitor's SendRecvBidiDataFromPort function, and returns the resulting buffer contents to the caller.
Additionally, a language monitor can create a separate thread that calls the port monitor's SendRecvBidiDataFromPort function to check for unsolicited status information or additional bidi information. If such an operation succeeds, the language monitor should return the status information to the spooler by a call to SetPort (described in the Windows SDK documentation).
In a port monitor server's DLL for locally connected devices, the SendRecvBidiDataFromPort function can call the DeviceIoControl or ReadFile functions to obtain data from the kernel-mode port driver. In a port monitor DLL for network-attached devices, the SendRecvBidiDataFromPort function calls network APIs to obtain bidirectional data from the printer and then sends the response back to the caller. For more information about DeviceIoControl and ReadFile, see the Windows SDK documentation.
Both language and port monitors can define SendRecvBidiDataFromPort functions and place their addresses in MONITOR2 structures. If a language monitor's SendRecvBidiDataFromPort function is defined, the spooler will always call it, whether or not a port monitor's SendRecvBidiDataFromPort function is defined.
In order to avoid stalling the spooler, SendRecvBidiDataFromPort should return within the time-out interval indicated in the lpCTO parameter in the call to the SetPortTimeOuts function, if the port monitor/language monitor supports this function.
A language monitor can call a port monitor's SendRecvBidiDataFromPort function outside a StartDocPort/EndDocPort function pair, or simultaneously with other port monitor calls, such as WritePort or ReadPort, but in a different thread. (Such a call might be generated by a thread checking for unsolicited status.) However, some port monitors might fail such a call, so the language monitor must be written to handle this failure. The spooler might also call a language monitor's SendRecvBidiDataFromPort routine outside a StartDocPort/EndDocPort pair or simultaneously with other calls, but in a different thread. A language monitor must be able to handle such calls. For more information about StartDocPort and EndDocPort, see the Windows SDK documentation.
The SendRecvBidiDataFromPort function should compare the granted access against PRINTER_ACCESS_ADMINISTER (described in the Windows SDK documentation) or any other ACCESS bit that the print provider intends to enforce. If the comparison fails, SendRecvBidiDataFromPort should return ERROR_ACCESS_DENIED.
For information about how to allocate memory for the response objects, see RouterAllocBidiMem and RouterAllocBidiResponseContainer. And to initialize a buffer suitable for the ppResData parameter, callers must use the RouterAllocBidiResponseContainer function.
Requirements
Target platform |
Desktop |
Version |
This function is available in Windows XP and later operating systems. |
Header |
Winsplp.h (include Winsplp.h) |
See also
RouterAllocBidiResponseContainer