SplRegister

This function allows applications to register for notification of events about printers. This function may be used for job accounting purposes or by printer drivers to keep aware of the operation of the print subsystem.

Syntax

 SplRegister(pszComputerName, pszName,
      hwndNotify, ulCategory, ulType, pulHandle);

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.

Returns

rc (ULONG) - returns

Return codes.

• 0 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.

Sample

#define INCL_SPL
#define INCL_SPLBIDI
#include <os2.h>

PSZ       pszComputerName;  /*  Printer server name to register for alert notification. */
PSZ       pszName;          /*  Case-sensitive name of printer port to register for alerts. */
HWND      hwndNotify;       /*  Window handle to get notify messages. */
ULONG     ulCategory;       /*  Category of alert to register. */
ULONG     ulType;           /*  Type of alert to enable for the given category. */
PULONG    pulHandle;        /*  Pointer to spooler alert handle. */
ULONG     rc;               /*  Return codes. */

rc = SplRegister(pszComputerName, pszName,
       hwndNotify, ulCategory, ulType, pulHandle);

Remarks

Note: Registration is not maintained across reboots.

Any new registration is in addition to existing registration(s) for the spooler handle passed in (if any handle was passed).

To remove registration, use SplUnRegister.

For each spooler alert handle, only the last hwndNotify passed in with the alert handle will be posted with alert messages.

That is, if you register window handle X and receive alert handle 1, then register for more alerts using window handle Y and alert handle 1, window handle Y will get alerts for alert handle 1, but window handle X will not get any alert messages.

Registration for alerts from a client on a print server requires that the user logged onto the client have authority to open a named pipe on the server. This access is normally granted to those users who have access to the print queue on a server.