Status Monitor API

Overview

The status monitor provides APIs for applications that request the printer status information.

One way for an application to be informed of the completion of a print job is to use GetJob() of Win32API on Windows2000/XP. However, this approach simply confirms the completion of the output transfer from the spooler to the printer; you cannot tell whether the entire print job has successfully been completed.

Using APIs provided by the status monitor, the client can obtain from the printer the information of "true completion of a print job."

  1. Function
  2. Identifier
  3. Program Flow
  4. Data structure in WM_COPYDATA
  5. Error Code
  6. Notes

Function

For custom applications, the status monitor provides the APIs as listed below.
You can download sample programs and header files from TOHOKU RICOH's Web site.

Function Name Description
Tric_RequestStatusNotify A function to request the status monitor to send the printer status information to the application.
Tric_ReleaseStatusNotify A function to cancel the request for the status monitor to send the printer status information.
Tric_RegistAllStatusGet A function to request the status monitor to send all the status data it has handled.
Tric_CancelAllStatusGet A function to cancel the request for all the status data.
Tric_WriteDocID A function to set DOCID, a document identifier.

To use these APIs from an application created on VisualC++, execute LoadLibrary() to load DLL.

Identifier

Operating the status monitor APIs require the following identifiers:

Identifier Description
SMONID The identifier for the status monitor. Its value can be obtained from the status monitor when the printer status information is requested (Tric_RequestStatusNotify).
DOCID The identifier for a document. The application can set a unique value for each document. Before a print job, this identifier is registered to the status monitor using Tric_WriteDocID. Documents can be identified through DOCID contained in the data obtained through the WM_COPYDATA messages.

Program Flow

This paragraph describes the flow of the programs using the status monitor APIs.

Case 1: For an application (AP1) to request the printer status information.
  1. Tric_RequestStatusNotify() is executed on AP1 to request the status monitor to send the printer status information to AP1. AP1 obtains the status monitor identifier (SMONID).
  2. With Tric_WriteDocID(), the application registers the identifier of a document (DOCID) to the status monitor.
  3. The document is printed.
  4. The status monitor sends the printer status information through a WM_COPYDATA message.
  5. With the execution of Tric_RequestStatusNotify(), the request for the status information is cancelled.

Case 2: For an application (AP2) to receive all the printer status data sent from the status monitor.
  1. With the execution of Tric_RegistAllStatusGet(), the status monitor is requested to send all of the printer status data.
  2. AP1 requests the printer status information, and the printer outputs images.
  3. The status monitor transmits a message to AP1. The contents of the same message(s) as sent to AP1 are transmitted to AP2 through the WM_COPYDATA message(s).
  4. With the execution of Tric_CancelAllStatusGet(), the request for all the status data is cancelled.

Data Structure in WM_COPYDATA

WM_COPYDATA sent from the status monitor to the application has the following structure:

wParam = NULL
lParam = A pointer to the COPYDATASTRUCT structure (defined in Winuser.h)
dwData TRIC_STATUS_SIGUNATURE(0x43495254)
cbData Size of the TRSM_STSHDR stucture
lpData A pointer to the TRSM_STSHDR structure

The TRSM_STSHDR structure (defined in tricsmon.h for the status monitor APIs) consists of the following members:

typedef struct tagTR_StsData {
    DWORD    dwSmonID;    // Status monitor identifier
    DWORD    dwDocID;     // Document identifier
    DWORD    dwDataType;  // Data type
    DWORD    dwDataSize;  // Data size: the size varies according to the data type
} TRSM_STSHDR, *PTRSM_STSHDR, FAR *LPTRSM_STSHDR;

Data Type
String Name (defined in tricsmon.h) Value Description Detailed data contents (size)
TRSM_DT_NONE 0 No data N/A (0Byte)
TRSM_DT_STARTDOC 1 Beginning of a print document N/A (0Byte)
TRSM_DT_ENDDOC 2 End of a print document N/A (0Byte)
TRSM_DT_PRINTED 3 End of a printed page Number of pages (4Byte)
TRSM_DT_ANSDATA 4 Response data Return value from the printer
TRSM_DT_PRNSTATUS 5 Printer status Printer error code (2Byte)

Printer Error Code List
For details of printer errors, refer to the "Operator’s Manual" of your printer. The language monitor can detect the following 2 kinds of errors:
Value Description
1001 Unable to read a printer response data
1002 Printer response timeout

Error Code

The following table lists the error codes used as return values from the functions when they are executed.

String Name (defined in tricsmon.h) Value Description
TRSM_ERR_SUCCESS 0 Success.
TRSM_ERR_SOCKET 1 The Socket communication failed.
TRSM_ERR_WINAPI 2 The execution of Win32API failed.
TRSM_ERR_NOSUPPORT 3 The request to the status monitor is not supported.
TRSM_ERR_MEMALLOC 4 Sufficient memory areas are not available.
TRSM_ERR_INVALID_PARAMETER 5 A parameter of the executed function is incorrect.
TRSM_ERR_SET_ALREADY 6 The value is already set to the status monitor.
TRSM_ERR_NOT_FOUND 7 The object requested to the status monitor is not found.
TRSM_ERR_SIZE_LARGE 8 Data size is too large.
TRSM_ERR_SIZE_SMALL 9 Data size is too small.
TRSM_ERR_REJECTED_SERVER 10 The status monitor server rejected the request.
TRSM_ERR_SMON_NORUNNING 11 The status monitor is not running.

Notes

  1. To obtain the status information from a Windows network printer, please set the spool format to RAW. The status information cannot be obtained with EMF.
  2. Executing Tric_WriteDocID() will not reflect the configurations until you make changes in the security settings of the status monitor API configuration file (hopesmon.tsm) if all of the following conditions are true:
In this case, go to the Security settings of the hopesmon.tsm file in the Windows directories and check the "Modify" box under "Allow."
<strong>Back</strong>