previous next

Chapter 10: Allowance Plug-in

An allowance plug-in is a server component that allows only certain requests or actions from a RealSystem G2 client. Applications that can use allowance plug-ins include:

Design Considerations

In addition to the general plug-in design considerations described in "Designing a Plug-In", keep the following points in mind as you develop your allowance plug-in:

  1. Optimize the allowance plug-in's use of processor time and memory. RealServer creates one instance of the allowance plug-in for each client stream—this means there will be at least one instance for each connected client. Plug-ins that require significant system resources can quickly degrade RealServer performance.

  2. Allowance plug-ins can only be used to control clients using the RSTP and PNA protocols. If the application must also stream content using HTTP, an allowance plug-in will not work.

  3. For a complete description of all the client and session properties that can be used as criteria for controlling connected clients, see "Appendix F: RealServer Property Registry".

  4. The allowance plug-in can be designed to receive notification of client and session property changes dynamically through the use of monitoring interfaces. See "Chapter 9: Monitor Plug-in", for details.

  5. An allowance plug-in is instantiated every time a client requests a stream, as mentioned above. Keeping this in mind as you read the following sections will help you understand how allowance plug-ins work and how to design them. For the sake of simplicity, we describe the initialization and functioning of the plug-in as if it were a single instance; that is, it is loaded when RealServer starts, and its IRMAPlayerConnectionAdviseSink::OnConnection method is called when the client connects. This explanation, while true, is somewhat simplified.

    Since the allowance plug-in gets created for each stream requested by a client, its start-up routines (RMACreateInstance, IRMAPlugin::GetPluginInfo, IRMAPlugin::InitPlugin) always get called before the server calls the plug-in's IRMAPlayerConnectionAdviseSink::OnConnection method. This detail is omitted from the discussion that follows, but understanding it will avoid confusion.

Interfaces

Allowance plug-ins typically use the following interfaces:

Coding the Plug-In

The following sections explain how RealServer and an allowance plug-in use the RealSystem interfaces to control client access. The sample files exallow.cpp and exppvpln.cpp, included with this SDK, illustrate many of these features. You can use these samples as a starting point for building your own plug-in. Refer to the RealSystem SDK header files for more information on function variables and return values.

Note
The order of function calls listed in the following sections provides a generalized explanation and is for illustrative purposes only. Because RealSystem is asynchronous, the plug-in must be able to handle any call made to it while it is processing data or waiting for a response from another object. Do not code the plug-in so that it expects a specific sequence of events to occur as it interacts with RealServer.

Starting Up

When RealServer starts up, it loads the allowance plug-in:

  1. RealServer calls RMACreateInstance to create an instance of an IRMAPlugin interface. See "Creating a Plug-In Instance" for more on this method.

  2. RealServer calls IRMAPlugin::GetPluginInfo, which returns descriptive information about the plug-in, including its copyright and "more information" URL. The bLoadMultiple property of IRMAPlugin::GetPluginInfomust be set to TRUE.

  3. RealServer calls IRMAPlugin::InitPlugin, which initializes the plug-in for use. Specifically, this method does two things:

  4. When a player connects to the RealServer, the server calls the plug-in's IRMAPlayerConnectionAdviseSink::OnConnection method, and passes a pointer to the IRMAPlayerConnectionResponse interface. The plug-in uses this response interface to respond to the various IRMAPlayerConnectionAdviseSink notifications sent by the server.

    It is important to remember that until the appropriate IRMAPlayerConnectionResponse method is called, nothing will happen with the connected player. For instance, the player will not be allowed to begin playback of a URL requested with IRMAPlayerConnectionAdviseSink::OnURL until the allowance plug-in calls IRMAPlayerConnectionResponse::OnURLDone.

  5. The RealServer will also call the plug-in's IRMAPlayerConnectionAdviseSink::SetPlayerController method to pass a reference to an IRMAPlayerController interface, specific to this player's connection. The plug-in uses this interface to control the player. The IRMAPlayerController methods are:

  6. The RealServer calls the plug-in's IRMAPlayerConnectionAdviseSink::SetRegistryID method to pass to the plug-in the ID for this player, stored in the RealServer Property Registry. This can be used to retrieve a number of the player's properties, such as its IP address, GUID, and the protocol it is using. See "Appendix F: RealServer Property Registry" and "Chapter 9: Monitor Plug-in" for more information.

  7. When the connected player requests a URL, the server calls the plug-in's IRMAPlayerConnectionAdviseSink::OnURL method, passing an IRMARequest interface. The requested URL is stored in this IRMARequest interface, along with the request headers.

    Your allowance plug-in can deal with this request in whatever way you decide. Very often, you will use one of the IRMAPlayerController interface's methods described above to disconnect or redirect the player—or you can take no action, in which case the server lets the player have the requested content. Remember, however, that the server does not release any content until the plug-in calls IRMAPlayerConnectionResponse::OnURLDone.

  8. During the life of the player's connection, various actions taken at the player will cause the RealServer to notify the plug-in by calling the appropriate IRMAPlayerConnectionAdviseSink methods. These are:

    Remember that the appropriate IRMAPlayerConnectionResponse method should be called as soon as the plug-in is done processing the notification.

Modifying the Allowance Plug-in Sample Code

The RealSystem SDK includes a couple of sample allowance plug-ins:

Follow the instructions in these files to test the samples or use them as the basis for your own plug-in.

Carry out the following steps to modify either sample file.

  1. Copy the source code from the samples directory to a working directory.

  2. Change the file names (exallow.cpp and exallow.h for the introductory allowance plug-in and exppvpln.cpp and exppvpln.h for the pay-per-view allowance plug-in) to something appropriate for your environment or application. Also change the class name (CExampleAllowance or CExamplePayPerView) to something suitable.

  3. Change the plug-in description, copyright, and more information URL stored in zm_pDescription, zm_pCopyright, and zm_pMoreInfoURL.

  4. Modify the implementation code for the various IRMAPlayerConnectionAdviseSink methods as needed:

  5. Compile, debug, and test your plug-in.

    Additional Information
    "Compiling a Plug-In".


Copyright © 2000 RealNetworks
For technical support, please contact supportsdk@real.com.
This file last updated on 05/17/00 at 12:50:20.
previous next