EnumPorts function pointer

Article
02/19/2018

A port monitor server DLL's EnumPorts function enumerates the ports that the port monitor supports.

Syntax

typedef BOOL ( WINAPI *pfnEnumPorts)(
  _In_     HANDLE  hMonitor,
  _In_opt_ LPWSTR  pName,
  _In_     DWORD   Level,
  _Out_    LPBYTE  pPorts,
  _In_     DWORD   cbBuf,
  _Out_    LPDWORD pcbNeeded,
  _Out_    LPDWORD pcReturned
);

Parameters

hMonitor [in]
Caller supplied monitor instance handle. This is the handle returned by the monitor's InitializePrintMonitor2 function. (This parameter does not exist if the print monitor supports InitializePrintMonitor instead of InitializePrintMonitor2.)
pName [in, optional]
Caller-supplied pointer to a string containing the name of the server whose ports are to be enumerated. A NULL pointer represents the system on which the port monitor server DLL is executing.
Level [in]
Caller-supplied value indicating the type of structures to be returned in the buffer pointed to by pPorts. Possible values are as follows:

Level pPorts

1

PORT_INFO_1

2

PORT_INFO_2
pPorts [out]
Caller-supplied pointer to a buffer to receive port information. Returned information must consist of an array of PORT_INFO_1 or PORT_INFO_2 structures, followed by the strings pointed to by structure members. These structures are described in the Microsoft Windows SDK documentation.
cbBuf [in]
Caller-supplied size, in bytes, of the buffer pointed to by pPorts.
pcbNeeded [out]
Caller-supplied pointer to a location to receive the buffer size, in bytes, required to contain all returned information.
pcReturned [out]
Caller-supplied pointer to a location to receive the number enumerated ports.

Level	pPorts
1	PORT_INFO_1
2	PORT_INFO_2

Return value

If the operation succeeds, the function should return TRUE. Otherwise it should return FALSE.

Remarks

Port monitor server DLLs are required to define an EnumPorts function and include the function's address in a MONITOR2 structure. Language monitors do not export this function.

The purpose of the EnumPorts function is to enumerate the ports currently supported by a print monitor. These ports are ones that were previously specified to the monitor's AddPortUI or AddPortEx function.

The EnumPorts function should fill the buffer pointed to by pPort with an array of PORT_INFO_1 or PORT_INFO_2 structures. Then starting in a memory location following the last array element, the function must load all the strings pointed to by the array's structure members. Refer to localmon.dll, a sample port monitor, for an example of how to do this. The function must also return the number of structures supplied (that is, the number of supported ports) by placing the number in the location pointed to by pcReturned.

The caller specifies the size of the supplied buffer in cbBuf. If the buffer is too small, the function should place the required buffer size in the location pointed to by pcbNeeded, call SetLastError (described in the Microsoft Windows SDK documentation) specifying ERROR_INSUFFICIENT_BUFFER, and return FALSE.

If Level contains an invalid level number, the function should call SetLastError specifying ERROR_INVALID_LEVEL, and return FALSE. Some port monitors only support a level value of 1.

The port monitor must support localization of strings pointed to by the pMonitorName and pDescription members of the PORT_INFO_2 structure. These strings should be defined in resource files and obtained by calling LoadString (described in the Windows SDK documentation).

The fPortType member of the PORT_INFO_2 structure is not used with NT-based operating systems.

Requirements

Target platform	Desktop
Header	Winsplp.h (include Winsplp.h)

Share via