The NetShow Event Notification and Authorization components use contexts to hold and pass around information about the server, user, or content. A context is an object wrapper of a data set and implements certain interface for manipulating the encapsulated data. For example, a server context encapsulates server information and exposes methods to access or to manipulate the server without having to know its underlying data structures. To have a plug-in component work with the server, user, or content amounts to specifying the appropriate server, user, or presentation context in the component and calling the methods of the interface. The context interfaces in NetShow inherit from the IPropertyMap interface. For more information about contexts supported by NetShow, see the discussion of “Event Notification Authorizatioin Contexts” in this document.
When the NetShow server is started, it retrieves from the system registry the class identifier (CLSID), and creates instances of all the notification and authorization plug-in components. Then the server and the components proceed to interact with each other in the following order.
The NetShow server calls the INSSEventHandler::Initialize method on each component to initialize the instantiated objects. The server passes in a pointer to the server context so that a component can use it to retrieve information about the server. The retrievable information includes:
The server context is available as long as the server is running. Later, the server can pass additional contexts into a component, such as a user context or a presentation context.
NetShow defines a heartbeat as a server timer event. A heartbeat can be used for timing other events and for monitoring the operational state of the server. You can have the server enable the heartbeat by specifying a positive value for the dwMsHeartbeatPeriod parameter in the Initialize method of the INNSSEventHandler interface. If a heartbeat is enabled, the server calls the INSSEventHandler::OnHeartbeat method at the regular intervals of the specified heartbeat period. Setting the dwMsHeartbeatPeriod parameter to zero disables the heartbeat.
For billing purposes, notification and authorization components can start their own timer events. For example, a component that authorizes the pay-per-minute Play event can start a timer once the user begins playing a title and can stop the timer when the user finishes viewing the title. The period of time from the start of play to the finish may be billable to the client if the server is up and running for the entire period. If, on the other hand, the server is down for sometime, the time interval clocked with the component’s timer may not be appropriate for the billing purpose. In this case, heartbeat is a preferred measure of time, because the OnHeartbeat method is only called while the server is up and running.
After initialization the server calls the INSSEventHandler::GetHandledEvents method of each component. This method is used to select events that will trigger a call to the event handler by the server. The following types of events are supported for notification.
After notification events are set, the server calls the QueryInterface method of the INSSEventAuthorization interface to determine whether or not the authorization interface is supported. All components must implement the INSSEventHandler interface. However, the INSSEventAuthorization interface is optional. When authorization is supported, the server invokes the INSSEventAuthorization::GetAuthorizedEvents method to retrieve the array of authorized events and thus determines which events will require authorization.
A component specifies which event must undergo the authorization process. You implement the scheme with the INSSEventAuthorization::GetAuthorizedEvents method. This method is similar to that specifying the events for notification. However, fewer events are supported for authorization. For instance, requiring authorization from the server before the client disconnects is not useful because the server cannot prevent a client from disconnecting.
You can specify the following events for authorization:
The NetShow server calls the INSSEventAuthorization::AuthorizeEvent method to determine whether it will perform the task assoicated with an event that requires authorization. When calling the method, the server supplies the component with information about the event, client, and content to be authorized.
If the authorization is a complicated and lengthy process, you should implement the AuthorizeEvent method in an asynchronous fashion, spawning another thread to determine if the request should be granted. Asynchronous implementation results in an immediate return of calls to the method and frees the server to proceed with other tasks while the authorization is in process. However, if the authorization is simple, as is in most cases, the method should return synchronously; that is, return a call after the authorization is done.
At the end of the authorization process, whether the request is granted or denied, the authorization component makes a call to the server to invoke the INSSEventAuthorizationCallback::OnEventAuthorizedmethod. A pointer to the callback interface is passed in by the server when it invokes the AuthorizeEvent method. The authorization component must call this method, whether the AuthorizeEvent method returns synchronously or asynchronously.
To uniquely identify the event requested for authorization, both the server and the authorization component pass the dwRequestId parameter to each other. The server passes the parameter into the component through the call to the INSSEventAuthorization::AuthorizeEvent method. The authorization component must pass the same request identifier back to the server through the call to the INSSEventAuthorizationCallback::OnEventAuthorized method.
Suppose that a user choses to play a title. If authorization is required to play the title, the server asks the event notification and authorization component to check on the user. When the user is authorized to play the title, the server then opens the title for user to play. If the authorization fails, the server will not open the requested title. In either case, the server calls the INSSEventHandler::HandleEvent method to notify the component whether or not the event occurs (in this case, whether the title is being played or not). If authorization is not required, the server will open the title for the user and then notify the component that the title is being played.
The server also notifies the component of any other events that are registered for notification and/or authorization by using the INSSEventHandler::GetHandleEvents method. The notification specifies the type of event requested and the results of the authorization, when applicable. You can choose to implement different responses to the notification in the INSSEventHandler::HandleEvents method. For example, you can present the viewing statistics of the client when the user connects to the server. Or you can announce the charge inccurred by the viewer when the title is stopped.
The following diagram illustrates a simple model of the sequence of calls between the NetShow server and the event notification and authorization interfaces. This chart assumes that there is only one authorization interface, and does not address client authentication.