IDeliveryProtocol.DeliverNotification Method

Artikkeli
12/03/2008

Activates the delivery protocol to package the notification data, if necessary, and to route it to the external delivery system.

Namespace: Microsoft.SqlServer.NotificationServices
Assembly: Microsoft.SqlServer.NotificationServices (in microsoft.sqlserver.notificationservices.dll)

Syntax

'Declaration
Sub DeliverNotification ( _
    headersList As NotificationHeaders(), _
    body As String _
)

void DeliverNotification (
    NotificationHeaders[] headersList,
    string body
)

void DeliverNotification (
    array<NotificationHeaders^>^ headersList, 
    String^ body
)

void DeliverNotification (
    NotificationHeaders[] headersList, 
    String body
)

function DeliverNotification (
    headersList : NotificationHeaders[], 
    body : String
)

Parameters

headersList
An array of NotificationHeaders objects containing the information needed to create the notification message and route it to the external delivery system.

Each NotificationHeaders object contains a NotificationState object, which is a RecipientInfo object that provides information about the recipient and a StringDictionary object containing the values of the protocol fields specified in the application definition. The array contains only one NotificationHeaders object unless the notification class uses multicast delivery is used. If the notification class uses multicast delivery, there is one NotificationHeaders object for each notification recipient.

body
A string containing the formatted notification data that was produced by the content formatter.

Remarks

The distributor uses this method to pass formatted notification data, which is created by the content formatter and passed as the body parameter, and header information, which is obtained from the protocol definition, to the delivery protocol. The delivery protocol then generates the notification message (if necessary) and hands it off to an external delivery system.

The distributor calls a delivery protocol's DeliverNotification method once for each message to be delivered. In the case of multicast delivery, each call to the DeliverNotification method can contain data from more than one notification. The delivery protocol creates the notification message from this information and routes the message for delivery. The message routing to the external delivery system can be accomplished in any way that is available to the developer and valid for the target delivery system. Often, this involves using transport mechanisms provided by the operating system.

The delivery protocol must use the notification status callback (whose delegate was passed to the Initialize method in the nsc argument) to pass a NotificationStatus object to the distributor for each notification passed as a NotificationHeaders object to the DeliverNotification method. The NotificationStatus object provides details on the outcome of each notification delivery attempt. Each NotificationStatus object contains the following fields:

NotificationState: An object used to convey notification information to the delivery protocol. The NotificationState object is passed to the delivery protocol for the express purpose of being passed back again as part of the notification delivery status information in a NotificationStatus object. The information contained in the NotificationState object is not used within the delivery protocol.
succeeded: A Boolean value indicating whether the notification message was handed off to the external delivery system successfully.
statusInfo: Additional delivery status information, such as an error message, or a text description of a status code. The value of statusInfo can be null if it is not needed by the delivery protocol.
notificationText: The content of the notification message. The value of notificationText can be null if it is not needed by the delivery protocol.
timeStamp: The time of the delivery attempt. The value of timeStamp can be null if it is not needed by the delivery protocol. If it is used, the time must be specified as a Universal Time Coordinate (UTC) time.

If multiple notifications are passed in a single call to DeliverNotification (that is, if the headersList array contains multiple NotificationHeaders objects), a NotificationStatus object must be provided to the distributor for each notification. This can be accomplished either by calling the notification status callback multiple times, or by passing multiple NotificationStatus objects to the notification status callback in a single call.

Determine when your implementation should invoke the notification status callback by balancing your requirement for application performance with your requirement for accuracy.

Each call to the notification status callback results in a round-trip to the database server. Sending multiple NotificationStatus objects in a single call improves performance by reducing the round-trips to the server. This requires the protocol implementation to cache the individual notification status values in memory until a sufficient number of them are collected. This situation leaves open the possibility of sending duplicate notifications if a server failure occurs and causes that in-memory cache to be lost before the status for those notifications is reported. You can mitigate this possibility by reporting the status of each notification individually immediately after it is sent, but this strategy results in more round-trips and some performance impact.

Important

If DeliverNotification throws an exception, you must not invoke the status callback for any of the notification headers passed in that call to DeliverNotification. Any exception thrown in this method is treated as a delivery failure. The notification delivery status is automatically set to Failed, thereby eliminating the need to set the status by using the callback.

For more information about delivery protocol definitions, see Configuring Delivery Protocols.

All notifications in a single batch that are going to the same delivery channel are processed on a single thread. The distributor may have many such threads executing in parallel, servicing different batches, or a single batch that has notifications destined for multiple delivery channels. The number of such threads that exist at any time is controlled by the system, but you can set an upper limit on it by means of the distributor's ThreadPoolSize setting.

When you implement the DeliverNotification method, you can choose to implement the delivery synchronously, returning only when delivery is complete, or asynchronously. At the end of the batch, the distributor will call the protocol’s Flush method, and wait for it to return. At the time Flush returns, all outstanding deliveries must either be completed or aborted, and status must be reported through the notification status callback.

Example

For an example of how to implement the DeliverNotification method, see the IDeliveryProtocol interface topic.

Thread Safety

Any public static (Shared in Microsoft Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

For a list of the supported platforms, see Hardware and Software Requirements for Installing SQL Server 2005.

Target Platforms