SplRegister - Parameters

pszComputerName (PSZ) - input

Printer server name to register for alert notification.

The field is used by an application running on a client machine to register for alerts on a print server. To register locally, this field must be NULL.

pszName (PSZ) - input

Case-sensitive name of printer port to register for alerts.

This value can be a virtual port name.

hwndNotify (HWND) - input

Window handle to get notify messages.

The message posted is as follows:

Message ID is WM_SPOOLER_ALERT(0x00d8)

MP1 will define the type of alert as follows:

/* Alert type - SHORT1FROMMP(MP1) bits 0-7 */
#define SPLMSG_SPECIAL_ALERT          0x00FC
#define SPLMSG_EXTENDED_ALERT         0x00FD
#define SPLMSG_CORE_ALERT_MASK        0x00FF

/* Extended alert type - SHORT1FROMMP(MP1) bits 8-15 */
#define SPLMSG_EXTENDED_TYPE_MASK     0xFF00

If the object type is SPLMSG_EXTENDED_ALERT, then this is an extended alert. The extended alert category is SHORT2FROMMP(MP1). The type of alert in the given extended alert category is SHORT1FROMMP(MP1) bits 8-15. This limits the notification given to applications registered for extended alerts to only the specific categories that are 0xFFFF or less and to only category types that are 0xFF or less.

If the object type is SPLMSG_SPECIAL_ALERT, then this is a special alert generated by the spooler and SHORT2FROMMP(MP1) will contain one of the following messages:

SPLMSG_CONNECTION_LOST - 0x0002

Connection to computer terminated; all alerts disabled for given computer.
SPLMSG_PORT_TERMINATED - 0x0003
Registration terminated for port.
SPLMSG_SPOOLER_DISABLED - 0x0001
Spooler disabled; all alerts for given computer are disabled.
If the object type is less than SPLMSG_SPECIAL_ALERT(0xFC), then this is a core alert. The specific core alert posted will be: SHORT1FROMMP(MP1) bits 0-7(SPLMSG_CORE_ALERT_MASK)


If the core alert is PRTALERT_TYPE_PAGE_PRINTED(9), then SHORT1FROMMP(MP1) bits 8-15(SPLMSG_PAGE_PRINTED_MASK) will be the page number printed. If the page number is above 255, the value hex 'FF' will be put in this byte field.

If the core alert is not PRTALERT_TYPE_PAGE_PRINTED(9), then SHORT1FROMMP(MP1) bits 8-15(SPLMSG_CORE_SEVERITY_MASK) will be the severity of the alert. SHORT2FROMMP(MP1) will be the spooler job ID if this is a core alert for a print job.

The core alert type will be one of the following:

Value

Description
1
PRTALERT_TYPE_INPUT
Input alert (Example: out of paper).
2
PRTALERT_TYPE_OUTPUT
Output alert (Example: output bin full).
3
PRTALERT_TYPE_JAM
Paper jam alert.
4
PRTALERT_TYPE_OPERATOR
Operator intervention required (Example: print ribbon jam).
5
PRTALERT_TYPE_CONFIG_CHANGE
Configuration changed (Example: cartridge removed).
6
PRTALERT_TYPE_SUPPLIES Supplies alert (Example: out of toner).
7
PRTALERT_TYPE_JOB_START
Job started printing.
8
PRTALERT_TYPE_JOB_STACKED
Job completed and stacked.
9
PRTALERT_TYPE_PAGE_PRINTED
Page printed.
10
PRTALERT_TYPE_JOB_CANCELLED
Job cancelled inside printer.
11
PRTALERT_TYPE_JOB_HELD
Job held inside printer.
12
PRTALERT_TYPE_COVER_OPEN
Cover or panel open.
13
PRTALERT_TYPE_POWER_ON
Printer powered on.
14
PRTALERT_TYPE_RESET
Printer reset.
15
PRTALERT_TYPE_ONLINE
Printer now online.
16
PRTALERT_TYPE_OFFLINE
Printer now offline.
17
PRTALERT_TYPE_TIMED_ALERT
Timed alert.
18
PRTALERT_TYPE_COMMUNICATION_PROBLEM
Communication problem.
19
PRTALERT_TYPE_COMM_STATUS_CHANGED
Communication status changed. BIDI_Q_PORT should be issued to get current state.
0xFF
PRTALERT_TYPE_OTHER
Other alert type (0xFFFFFFFF).
The severity of the problem will be one of the following:

Value

Description
00
PRTALERT_SEV_INFORMATIONAL
01
PRTALERT_SEV_WARNING
02
PRTALERT_SEV_ERROR
Printing stopped due to error.
03
PRTALERT_SEV_SERVICE
Service is required.
04 - FD
Reserved
FE
PRTALERT_SEV_OTHER
Other (0xFE)
FF
PRTALERT_SEV_UNKNOWN
Unknown (0xFF)
MP2 contents are as follows: SHORT1FROMMP(MP1) is the atomized print server name.
If the notification is from the local spooler, this value will be zero.

SHORT2FROMMP(MP2) is the atomized print queue name when the
message involves a print job (alert values 7 - 11);
otherwise, it will be the atomized printer port name, if applicable.


ulCategory (ULONG) - input

Category of alert to register.

This value can be the core alert category or an extended alert category as defined below:

PRTALERT_CATEGORY_CORE - 0x00000001

Core alert category
PRTALERT_CATEGORY_EXTENDED - 0x0000D000
Beginning of the extended alert categories. Protocol converters should limit the category range to between 0x0000D000 and 0x0000DFFFF.
PRTALERT_CATEGORY_EXT_MAX - 0x0000DFFF
End of the extended alert categories.
If the protocol converter does not support the given category, ERROR_INVALID_CATEGORY(117) is returned.

ulType (ULONG) - input

Type of alert to enable for the given category.

If the category is PRTALERT_CATEGORY_CORE, this is a bit-field that defines the additional core alerts to enable. The core alerts corresponding to the bits set in the ulType field will be enabled, in addition to any currently enabled core alerts. If the protocol converter does not understand one of the bits that are set, ERROR_INVALID_FLAG_NUMBER(186) should be returned.

If the printer is not capable of setting one of the core alerts whose bit is set, and if any core alerts can be enabled, a Success return code should be returned.

If the category is not PRTALERT_CATEGORY_CORE, then this is a value that defines the specific extended alert to enable.

Bit defintions for core alerts are as follows:

Bit

Description
0
PRTALERT_CORE_INPUT - 0x00000001 Input alert (Example: out of paper).
1
PRTALERT_CORE_OUTPUT - 0x00000002
Output alert (Example: output bin is full).
2
PRTALERT_CORE_JAM - 0x00000004
Paper jam alert.
3
PRTALERT_CORE_OPERATOR - 0x00000008
Operator intervention required (Example: print ribbon jam).
4
PRTALERT_CORE_CONFIG_CHANGE - 0x00000010
Configuration changed (Example: cartridge removed).
5
PRTALERT_CORE_SUPPLIES - 0x00000020
Supplies alert (Example: out of toner).
6
PRTALERT_CORE_JOB_START - 0x00000040
Job started printing.
7
PRTALERT_CORE_JOB_STACKED - 0x00000080
Job completed and stacked.
8
PRTALERT_CORE_PAGE_PRINTED - 0x00000100
Page printed.
9
PRTALERT_CORE_JOB_CANCELLED - 0x00000200
Job cancelled inside printer.
10
PRTALERT_CORE_JOB_HELD - 0x00000400
Job held inside printer.
11
PRTALERT_CORE_COVER_OPEN - 0x00000800
Cover or panel open.
12
PRTALERT_CORE_POWER_ON - 0x00001000
Printer powered on.
13
PRTALERT_CORE_RESET - 0x00002000
Printer reset.
14
PRTALERT_CORE_ONLINE - 0x00004000
Printer now online.
15
PRTALERT_CORE_OFFLINE - 0x00008000
Printer now offline.
16
PRTALERT_CORE_TIMED_ALERT - 0x00010000
Timed alert.
17
PRTALERT_CORE_COMMUNICATION_PROBLEM - 0x00020000
Communication problem.
18
PRTALERT_CORE_COMM_STATUS_CHANGED - 0x00040000
Communication status changed.

pulHandle (PULONG) - in/out

Pointer to spooler alert handle.

For initial registration, the value pointed to by this parameter should be 0 (zero). If an application wants to make better use of spooler resources, the application can use the same returned spooler handle for all of its alert registration.

rc (ULONG) - returns

Return codes.
• Success

  ERROR_INVALID_CATEGORY(117)

  The protocol converter does not support the extended alert category.
  ERROR_INVALID_FLAG_NUMBER(186)
  The protocol converter did not understand a core alert that was set.
  ERROR_INVALID_HANDLE(6)
  The value pointed to by pulHandle is not a valid spooler alert handle. The value at *pulHandle should be set to 0 (zero) to allocate a new spooler alert handle.
  ERROR_INVALID_PARAMETER(87)
  An invalid buffer given.
  ERROR_NOT_SUPPORTED(50)
  The spooler on the given print server cannot support alert notification.
  PMERR_SPL_SPOOLER_NOT_INSTALLED(0x4009)
  The spooler is not enabled.

  ---

  [Back: SplRegister Return Value - rc]
  [Next: SplRegister - Remarks]