# IMessaging.RegisterNotification()

Description:

The `RegisterNotification` method registers the widget to receive notifications of new incoming messages. For each new message, the method returns the header information of that message.

This is an asynchronous method.

Syntax:

    result = so.IMessaging.RegisterNotification(criteria, callback);

Arguments:

- `criteria`:

  This is an object that specifies the request for notification of new messages. The object must contain the `Type` property (string), and this property must contain the value `"NewMessage"`:

      criteria.Type = "NewMessage";

- `callback`:

  The `callback` argument is the name of the method that is executed when `RegisterNotification` has results or status information to return. You must define this method separately. Follow the instructions in section Defining the callback handler for an asynchronous method to define the `callback` method.

Return value:

The `RegisterNotification` method returns an object that contains the initial return value for the asynchronous call it started (see the following table). The actual notification information is returned by the `callback` method in the `ReturnValue` property of its result object. The returned information is described in section Returned notification information.

Table: Return value properties for RegisterNotification
Property | Description | Value
--- | --- | ---
`result.TransactionID` | This is a number used as an identification to match transactions started with a `RegisterNotification` call to one or more calls it generates to `callback`. |
`result.ErrorCode` | This is a number that specifies a predefined error code. | See Service API error codes.
`result.ErrorMessage` | This is a text string that describes the error. | See Messaging Service API error messages.

Remarks:

`RegisterNotification` retrieves new message updates until cancelled with `CancelNotification` (or `Cancel`). You can therefore have only one `RegisterNotification` call (one instance) pending or in use at any given time.

Example code:

For the complete source of a sample widget that demonstrates how to use this Service API, see the full example.