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:
In this application, the plug-in checks a URL requested by the client. If the URL is secure, the plug-in forces the client to authenticate the URL. See "Chapter 19: Authentication", for more information.
In this application, the plug-in checks the IP address of the connecting client and disconnects the client if the IP address is not within a particular range (domain restriction), is not found on a list of authorized IP addresses (membership restriction), or fails to meet any other IP address criteria.
In this application, the plug-in redirects incoming clients to different clips based on the time of day, player version, connection bandwidth, or any other available criteria.
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:
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.
Allowance plug-ins typically use the following interfaces:
IRMAPlugin
. Header file: rmaplugn.h
. Every plug-in implements this interface, which RealSystem uses to determine the plug-in's characteristics.
IRMAPlayerConnectionAdviseSink
. Header file: rmaallow.h
. The allowance plug-in implements this interface, and its methods are called by the server as various client actions occur.
IRMAPlayerConnectionResponse
. Header file: rmaallow.h
. This interface is implemented by RealServer core and is passed to the allowance plug-in as a parameter to IRMAPlayerConnectionAdviseSink::OnConnection
. The plug-in uses this interface to tell the server when the plug-in is finished with a specific IRMAPlayerConnectionAdviseSink
notification.
IRMAPlayerController
. Header file: rmaallow.h
. This interface is implemented by RealServer and is passed to the allowance plug-in as a parameter to IRMAPlayerConnectionAdviseSink::SetPlayerController
. Using this interface, the plug-in can control the client by telling RealServer to alert, redirect, or disconnect that client.
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.
When RealServer starts up, it loads the allowance plug-in:
RMACreateInstance
to create an instance of an IRMAPlugin
interface. See "Creating a Plug-In Instance" for more on this method.
IRMAPlugin::GetPluginInfo
, which returns descriptive information about the plug-in, including its copyright and "more information" URL. The bLoadMultiple
property of IRMAPlugin::GetPluginInfo
must be set to TRUE
.
IRMAPlugin::InitPlugin
, which initializes the plug-in for use. Specifically, this method does two things:
IRMACommonClassFactory
interface. This interface creates commonly-used RMA interfaces such as IRMAPacket
, IRMAValues
, and IRMABuffer
.
IRMAPNRegistry
interface, which retrieves various properties of the connected player and the session (see IRMAPlayerConnectionAdviseSink::SetRegistryID
, item 6. below).
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
.
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:
IRMAPlayerController::Pause
pauses the player.
IRMAPlayerController::Resume
the player resumes playing at the point it was paused.
IRMAPlayerController::Disconnect
the connection to the player is dropped.
IRMAPlayerController::AlertAndDisconnect
same as IRMAPlayerController::Disconnect
, but a message is displayed on the player.
IRMAPlayerController::HostRedirect
redirects the player to another host or port, at the same URL.
IRMAPlayerController::NetworkRedirect
Redirects the player to another URL. This method only works to redirect an RTSP connection to another RTSP URL.
IRMAPlayerController::Redirect
redirects the player to another URL on the same server. This method works with both RTSP and PNA protocols.
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.
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 playeror 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
.
IRMAPlayerConnectionAdviseSink
methods. These are:
IRMAPlayerConnectionAdviseSink::OnURL
as described above, the player has requested a URL. After processing this notification, the plug-in should respond with IRMAPlayerConnectionResponse::OnURLDone
.
IRMAPlayerConnectionAdviseSink::OnBegin
the player has begun or resumed playback. The response is IRMAPlayerConnectionResponse::OnBeginDone
.
IRMAPlayerConnectionAdviseSink::OnPause
the player has paused the playback. The response is IRMAPlayerConnectionResponse::OnPauseDone
.
IRMAPlayerConnectionAdviseSink::OnStop
the player has stopped the playback. The response is IRMAPlayerConnectionResponse::OnStopDone
.
IRMAPlayerConnectionAdviseSink::OnDone
the player has disconnected from the server. There is no response to this notification.
Remember that the appropriate IRMAPlayerConnectionResponse
method should be called as soon as the plug-in is done processing the notification.
The RealSystem SDK includes a couple of sample allowance plug-ins:
/samples/intro/exallow/exallow.cpp
This sample plug-in monitors client connections to the server and makes decisions about what each client is allowed to do. It receives a notification for each significant event in a client's connection lifetime, and can restrict the client's rights by, for example, disconnecting, redirecting, authenticating, or granting limited permissions to the client for content playback.
/samples/intermed/exppvpln/exppvpln.cpp
This sample plug-in parallels the content of the introductory allowance plug-in, but is specifically written to handle pay-per-view authentication. It monitors all incoming client connections, and password protects all URLs that contain the word "protected" in them. When a client attempts to access this URL, this plug-in triggers the authentication process and, if the client is successfully authenticated, the client is allowed to play the content.
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.
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.
zm_pDescription
, zm_pCopyright
, and zm_pMoreInfoURL
.
IRMAPlayerConnectionAdviseSink
methods
as needed:
IRMAPlayerConnectionAdviseSink::OnConnection
to retrieve client information from the RealServer Property Registry. You might also want to use various monitoring interfaces to set watches on some of these properties. See Chapter 9, Monitor Plug-In, and Appendix C, RealServer Property Registry, for more information.
IRMAPlayerConnectionAdviseSink
methods. IRMAPlayerConnectionAdviseSink::OnURL
, IRMAPlayerConnectionAdviseSink::OnBegin
, IRMAPlayerConnectionAdviseSink::OnPause
, IRMAPlayerConnectionAdviseSink::OnStop
, and IRMAPlayerConnectionAdviseSink::OnDone
will probably all need to be modified. Remember that all but the last of these must call its corresponding IRMAPlayerConnectionResponse
method with PNR_OK
. Also remember that the quicker your plug-in can process the notification and call the response interface, the better.
![]() |
Additional Information |
---|
"Compiling a Plug-In". |