EnumPorts

BOOL (WINAPI *pfnEnumPorts)(

LPWSTR pName,
DWORD Level,
LPBYTE pPorts,
DWORD cbBuf,
LPDWORD pcbNeeded,
LPDWORD pcReturned
);

EnumPorts enumerates the ports available for printing on a specified server.

Parameters

pName

Points to a zero-terminated string that specifies the name of the server whose ports are to be enumerated. If this parameter is null, local ports are enumerated.

Level

Specifies the version of the structure to which pPorts points. This value must be one or two.

pPorts

Depending on Level, points to an array of PORT_INFO_1 or PORT_INFO_2 structures where data describing all of the available ports is to be written.

cbBuf

Specifies the size, in bytes, of the buffer to which pPorts points.

pcbNeeded

Points to a DWORD in which the buffer size required to hold all enumeration data is returned.

pcReturned

Points to a DWORD in which the number of PORT_INFO_1 or PORT_INFO_2 structures written to pPorts is returned.

Return Value

The return value is TRUE if the function is successful; otherwise, it is FALSE.

Comments

The spooler calls EnumPorts to get the list of ports maintained by a monitor. At spooler initialization, the spooler calls EnumPorts for all installed print monitors to build up a list of all available ports. The spooler expects valid results from EnumPorts regardless of whether a printer has yet been defined.

If a monitor doesn’t support the structure specified by Level, EnumPorts should log an ERROR_INVALID_LEVEL error and fail.

If cbBuf is too small, EnumPorts should set ERROR_INSUFFICIENT_BUFFER, and return in pcbNeeded the number of bytes required to copy all of the data. If cbBuf is large enough, EnumPorts should return the number of bytes copied into pPorts.

EnumPorts must write the PORT_INFO_Xx structure(s) at the beginning of the pPorts buffer, and the string(s) associated with the PORT_INFO_Xx structure(s) at the end of the buffer. Monitors that do not pack data in this way will cause Win32 EnumPorts calls to the spooler to fail. See the localmon code for an example of how to pack the pPorts buffer.

Monitors should set the pMonitorName field of the PORT_INFO_2 structure to be a string that describes their monitor. It is the monitor’s responsibility to localize this string. Monitors should set PORT_INFO_2’s fPortType field to zero.

EnumPorts is a port management function that must be implemented by port monitors and LMPMs. Pure language monitors should not implement this function.

See Also

AddPort, AddPortEx, DeletePort