Theater SDK Banner 

Art
[Previous][Next]

Pay-per-Minute Authorization Component Sample

The Pay-per-Minute authorization component sample, written in C++, provides a working example of how to write a NetShow Theater Server authorization plug-in component. The source code can be found in the \NetShowTheaterRoot\SDK\Admin\Authorization\ppm directory. Here, \NetShowTheaterRoot is the root directory in which NetShow Theater Server is installed.

You can build and register the sample component either in Microsoft® Visual Studio® 97 (by opening NSPayPerMinutePlugin.dsw workspace file, and on the Tools menu, clicking Build) or from an MS-DOS shell (by typing the NMAKE -f NSPayPerMinutePlugin.mak command). To compile the source code, you might need to copy \NetShowTheaterRoot\Theater\Admin\Lib\NSTAdmin.ocx from a computer that has the NetShow Theater Server Administration Tools installed in the sample compilation directory.

You must run the ppm.reg script in the \NetShowTheaterRoot\SDK\Samples\Commerce\Dlls\ directory to add the \HKEY_LOCAL\MACHINE\Software\Microsoft\NetShow\Servers\Default\Event Notification\PayPerMinute Module key to the registry. The computer running NetShow Theater Server uses this key to determine if the sample authorization plug-in component is to be used for event authorization.

The registry entry contains information about the data source as well as the user name and/or password that must be used to access the data source. The database schema is specified in \NetShowTheaterRoot\SDK\Samples\Commerce\Store\Config\SQL\SQLSvr\Schema.sql

About the Component and its Design

The Pay-per-Minute Authorization component implements a business logic to grant permission for a client to view a NetShow Theater Server title if the user has an active account with a positive balance. The user is charged a fee based on the amount of time the title has been streamed. Authorization is performed against the information available in the connected database. Users viewing the title are disconnected when funds are depleted from their accounts. However, while viewing a title, users can add funds to their accounts to ensure uninterrupted service. The Pay-per-Minute authorization component is only activated when the open title has a PPM Charge Type attribute.

The main class is NSPayPerMinute, which implements the INNSEventNotification and INNSEventAuthorization interfaces for NetShow Theater Server event notification and authorization. The NSPayPerMinute class handles all the communications to and from NetShow Theater Server. It notifies the server of the type of events it will handle for notification and/or authorization (see GetHandledEvents and GetAuthorizedEvents). It responds to NetShow Theater Server authorization requests and event notifications from the server (see AuthorizeEvent, OnEvent, OnHeartBeat, and so on). It notifies the server of the result of authorization, by invoking the OnEventAuthorized callback function, after receiving an AuthorizeEvent call.

Because calls to AuthorizeEvent, OnEvent, and OnHeartBeat must return values asynchronously (so as not to tie up a server thread for too long), most of the actual work involved in authorization and event notification is passed to separate worker threads (see WorkerThreadProc) through a Microsoft® Windows® IO completion port.

The NSPayPerMinute class also uses the CDataAccess class to maintain a connection to an ADO/ODBC data source for executing database queries and updates. The NSPayPerMinute and CDataAccess classes are contained in the NSPayPerMinute.cpp and CDataAccess.cpp files, respectively.

NSPayPerMinute Object

The NSPayPerMinute object uses a CAuthRequest data structure to hold information regarding an authorization request in order to pass information from the authorization request to the OPEN and CLOSE events. A pointer to this data structure is stored in the PPMContextPointer attribute of the presentation context.

Upon initialization, the NSPayPerMinute object first retrieves the data source and database user logon information from the \HKEY_LOCAL_MACHINE\Software\NetShow\Servers\Default\Event Notification\PayPerMinute Module registry key. It then creates an instance of the CDataAccess class that uses the user name and password retrieved from the registry to open a connection to the data source. It also spawns a number of worker threads that are used later to actually process the authorization and event handling requests.

The GetHandledEvents method specifies that the component handles only OPEN and CLOSE events, while the GetAuthorizedEvents method specifies that only SKIP_AUTHENTICATION and OPEN events are subject to authorization. You can customize these methods if you have different authorization and event notification needs.

When a user attempts to open a title, the computer running NetShow Theater Server first queries the component to determine whether authentication is required. The component then checks if the title is of the PPM Charge Type and, if so, responds that authentication is required. After authenticating the user by using a separate authentication component, the server requests that the Pay-per-Minute component authorize the OPEN event. The component authorizes the OPEN event if the user account is active and has a positive account balance.

At this point, a CAuthRequest data structure is created and stored in the PPMContextPointer attribute of the presentation context. When the server notifies the component of the OPEN event, the current time as well as the amount of time the user is allowed to watch (based on the user's account balance and the cost of the title per minute) is calculated, and entered into a priority queue. Finally when the server notifies the component of the CLOSE event, the exact amount that the user must be charged is calculated and then deducted from the user account balance.

The NSPayPerMinnute object uses the OnHeartbeat event to periodically check the priority queue. This determines whether any clients must be stopped from streaming a title due to depletion of funds in the user’s account. However, it queries the database before closing the client, in case the user has added funds while the title was being played.

Data Access Object

The Data Access Object, an instance of the CDataAccess class, manages a connection to an ADO/ODBC data source in order to carry out queries and updates to the database. Following is a summary of the database-related operations:

Verifying that the Pay-per-Minute payment plan is required for playing a given title (see the RequirePayment method). Verifying that the viewer has sufficient funds to watch a title (see the CheckPayment method). Retrieving the balance of the user account (see the GetBalance method). Updating the active count of the user account when the user chooses to open the stream (see the CommitOpenViewing method). Updating the user account balance when the viewer closes the stream (see the CommitCloseViewing method), Retrieving the per-minute list price for watching a title (see the RetrivesStream method). Logging the user access information to the stream (see the LogStreamAccess method).

[Previous][Next]



© 1996-1998 Microsoft Corporation. All rights reserved