C API applications can call the signal handlers that Domino and Notes use to report events to the user. They can also create signal handlers to perform customized processing when a signal occurs or to disable normal signal handling while performing specialized tasks. Please be aware that Notes C API programs should not install operating system signal functions (for example: signal(), sigset(), etc), because it is not supported.
Signal handlers are different from normal API functions. There are no function names that you can code in an application. Instead, Domino or Notes stores pointers to signal handler functions in an internal table. To obtain the current address of a signal handler, call the API function OSGetSignalHandler. To set a new signal handler, call the API function OSSetSignalHandler.
There is a separate internal signal handler table for each process. A custom signal handler only "catches" signals from operations performed in the current process; it does not handle signals from other processes. Furthermore, a call to a signal handler from a process is only handled by the "default" signal handlers for that process; if another process sets a custom signal handler, calls from the first process are not affected.
The result of calling the default signal handlers depends on whether the application is running in the Notes client or Domino server environment. If the application runs in the context of the Notes client workstation process, the signal behavior (such as OS_SIGNAL_MESSAGE) is GUI-based. If the application runs in the context of a server add-in process, the signal behavior is character-based. For example, OS_SIGNAL_MESSAGE will only log a message to log.nsf and the console; no GUI message box is put up.
The C API supports the following signals:
OS_SIGNAL_MESSAGE Display a message to the user
OS_SIGNAL_BUSY Paint a busy indicator on the screen
OS_SIGNAL_CHECK_BREAK Check for user cancellation of I/O
OS_SIGNAL_DIAL Prompt to dial a remote system
OS_SIGNAL_PROGRESS Display the progress bar
OS_SIGNAL_REPL Signal the replication state
Each of these signals and the corresponding signal handler is described in detail below.
Calling a Signal Handler
The C API allows applications to obtain the addresses of the signal handlers that are built into Domino and Notes and to call these signal handlers in the same way that Domino and Notes call them. This can be useful, for example, when building applications that need to display messages to the user; you can use the signal handler for OS_SIGNAL_MESSAGE to display a dialog box and get a response from the user. As another example, you can use the OS_SIGNAL_BUSY message handler to display a busy indication on the user's screen.
To call a signal handler, follow these steps:
- Call OSGetSignalHandler to obtain the address of the signal handler, passing as the argument the appropriate signal ID. If no signal handler is present, this function returns NULL.
- Call the signal handler using the address and the appropriate argument list. The return value depends on the specific signal handler; for details, refer to the description of the signal handler.
For example, the following code fragment illustrates a call to the message signal handler:
- #include <ossignal.h>
MessageProc = (OSSIGMSGPROC) OSGetSignalHandler (OS_SIGNAL_MESSAGE);
if (NULL != MessageProc)
result = (*MessageProc) ("Press 'OK' to continue",
Supplying a Custom Signal Handler
You can also supply a custom signal handler, either to provide special processing for a signal or to disable the normal handling of a signal. Use OSSetSignalHandler to set a signal handler for the current process, providing the signal ID and the address of the new signal handler. OSSetSignalHandler returns the address of the current signal handler for the process; to ensure that normal processing of signals will resume, applications should restore this signal handler address when finished.
To disable normal handling of system events, set the signal handler address to NULL, as the following code fragment illustrates:
- #include <ossignal.h>
OldBusyProcPtr = OSSetSignalHandler (OS_SIGNAL_BUSY, (OSSIGPROC) NULL);
/* Code to execute with no busy indication */
OSSetSignalHandler (OS_SIGNAL_BUSY, OldBusyProcPtr);
Setting a custom signal handler for the OS_SIGNAL_MESSAGE is not supported in the C API. You may call the built-in signal handler for OS_SIGNAL_MESSAGE to display messages at the Notes UI.
Built-In Signal Handlers
The following sub-sections describe the signal handlers that are built into Domino and Notes.
The Message Signal Handler
Notes workstation clients use the message signal handler to display message boxes to the user via a graphical user interface. The built-in signal handler can post a message to the status line on the display or display a message in a dialog box with buttons; the type of display is controlled by the Type parameter passed to the signal handler.
This signal handler requires two parameters:
- Message - Far pointer to message text to be displayed
- Type - How the message is to be displayed. The values allowed for this parameter are:
- Display the message in a dialog box with an OK button.
- Display the message in a dialog box with OK and CANCEL buttons.
- Display the message in a dialog box with YES and NO buttons.
- Display the message in a dialog box with YES, NO, and CANCEL buttons.
- Display the message in a dialog box with RETRY and CANCEL buttons.
- Display the message on the status line.
This signal handler returns a status code that identifies the user's action. The return codes are:
- ERR_OSMESSAGE_OK User selected OK
ERR_OSMESSAGE_CANCEL User selected CANCEL
ERR_OSMESSAGE_RETRY User selected RETRY
ERR_OSMESSAGE_YES User selected YES
ERR_OSMESSAGE_NO User selected NO
If the dialog box cannot be loaded, the error code ERR_OSMESSAGE_CANNOT_PROMPT is returned. A call to the message signal handler with the parameter OSMESSAGETYPE_POST always returns ERR_OSMESSAGE_OK. Applications can obtain the address of the message signal handler by calling OSGetSignalHandler (OS_SIGNAL_MESSAGE).
In the Domino server environment, only OSMESSAGETYPE_POST is enabled. A call to the mMessage signal handler with this type code records an entry in log.nsf containing the message text if logging is enabled; otherwise, it displays the message on the server console. Using any other type code results in an error message.
The Busy Signal Handler
The low-level I/O code in the Notes core DLLs uses the busy signal handler to indicate when I/O operations are taking place. The Notes client workstation code provides a signal handler that displays the "lightning bolt," indicating network activity, when BUSY_SIGNAL_NET_ACTIVE is signaled and erases it when BUSY_SIGNAL_NET_INACTIVE is signaled. Applications can provide a custom signal handler to take action when Notes starts or completes an operation.
Five different events are signaled, identified by the BusyType parameter to the signal handler:
- BUSY_SIGNAL_FILE_ACTIVE Starting local disk I/O operation
BUSY_SIGNAL_FILE_INACTIVE Local disk I/O completed
BUSY_SIGNAL_NET_ACTIVE Starting network I/O operation
BUSY_SIGNAL_NET_INACTIVE Network I/O completed
BUSY_SIGNAL_POLL Checking to see if network I/O has completed
To obtain the address of the busy signal handler, call OSGetSignalHandler (OS_SIGNAL_BUSY). To install a custom signal handler, call OSSetSignalHandler().
The default signal handler in the Notes client workstation reacts only to BUSY_SIGNAL_NET_ACTIVE and BUSY_SIGNAL_NET_INACTIVE to control display of the network activity indicator. The other actions are ignored to speed up the operation of Notes. The low-level I/O code in the Notes core DLLs invokes this signal handler frequently. BUSY_SIGNAL_FILE_ACTIVE and BUSY_SIGNAL_FILE_INACTIVE are called before and after each disk I/O operation. BUSY_SIGNAL_NET_ACTIVE and BUSY_SIGNAL_NET_INACTIVE are called before and after each network I/O operation, and BUSY_SIGNAL_NET_POLL is called each time Notes checks to see if a network operation has completed. These events can happen many times per second (particularly BUSY_SIGNAL_NET_POLL), so be careful when writing a custom signal handler to avoid slowing the operation of Notes.
In the server environment, since there is no GUI interface, the busy signal handler has no effect and always returns NOERROR.
The Check Break Signal Handler
The check break signal handler is called when the Notes client workstation and the Domino server test to see if a "break" event has occurred. There are different signal handlers for the Notes client and the Domino server, so the behavior is different in each environment. For Notes clients, the check break signal handler returns ERR_CANCEL if the user has pressed the key combination to generate the break signal; otherwise, it returns NOERROR. For Domino servers, the check break signal handler returns ERR_QUIT if the task (or server) has been commanded to quit; otherwise, it returns NOERROR. Applications can obtain the address of the check break signal handler by calling OSGetSignalHandler (OS_SIGNAL_CHECK_BREAK). This signal handler requires no parameters.
The Dial Signal Handler
In the Notes client workstation environment, the dial signal handler displays a dialog box where the user can specify options for dialing a server. This signal handler is called before initiating an external dial. It returns ERR_NET_CONTINUE if the number is to be dialed; any other return value is an error code to be reported to the application. This signal handler requires five parameters:
- pServer - Far pointer to a null-terminated string containing the name of the server to dial
- pPort - Far pointer to a null-terminated string containing the name of the port to use
- pDialParams - Reserved for future use; should be set to NULL
- pRetServer - Pointer to a buffer to hold the actual name of the server to call
- pRetPort - Pointer to a buffer to hold the actual name of the port to use
Applications can obtain the address of the dial signal handler by calling OSGetSignalHandler (OS_SIGNAL_DIAL).
In the Domino server environment, the dial signal handler has no effect and always returns ERR_NET_CONTINUE.
The Progress Signal Handler
The Progress signal handler displays a progress bar. This signal handler requires three parameters:
- Option - Specify one of the following options:
- data1 - Depending on the value of the Option, this parameter supplies the header text, the range, or the position of the progress bar.
- data2 - Reserved for future use; should be set to NULL
The Repl Signal Handler
The Repl signal handler signals the state of the replication. This signal handler requires three parameters:
- State - Specify one of the following states:
- pText1 - Pointer to a null terminated string identifying the server.
- pText2 - Pointer to a null terminated string identifying the server.