previous next

Appendix F: RealServer Property Registry

RealServer maintains a Property Registry that contains a variety of information about the server's configuration and current load, connected clients, and each client's sessions. The RealServer Property Registry can also be used to store new, user-defined properties, which can be changed or deleted by the process that created them. All these properties, whether predefined or user-defined, can be retrieved by server plug-ins through the use of interfaces designed for this purpose. Server plug-ins can also arrange to be notified when specific properties change.

Additional Information
See "Chapter 9: Monitor Plug-in" to learn how to create a plug-in that monitors properties in the RealServer Property Registry.

Registry Basics

The RealServer Property Registry is a hierarchical structure of Name/Value pairs (properties) which is capable of storing many different types of data including strings, buffers, and integers. The registry provides various types of information including server and client statistics, configuration information, and system status. Each Registry Property has a name, ID, datatype, and value. The registry interfaces provided by RealServer include methods for the setting and retrieval of properties by name or by ID.

Registry Datatypes

The following table lists the registry datatypes currently available for use. The Methods column lists the methods supported for each datatype..

Server Registry Datatypes
Datatype Methods Method Description
Integer
Signed 32-bit
IRMAPNRegistry::AddInt Adds a new property.
IRMAPNRegistry::GetIntByName Retrieves a value using the property name.
IRMAPNRegistry::GetIntById Retrieves a value using the property ID.
IRMAPNRegistry::SetIntByName Sets a value using the property name.
IRMAPNRegistry::SetIntById Sets a value using the property ID.
String
NULL terminated unsigned char* within an IRMABuffer
IRMAPNRegistry::AddStr Adds a new property.
IRMAPNRegistry::GetStrByName* Retrieves a value using the property name.
IRMAPNRegistry::GetStrById* Retrieves a value using the property ID.
IRMAPNRegistry::SetStrByName Sets a value using the property name.
IRMAPNRegistry::SetStrById Sets a value using the property ID.
Buffer
IRMABuffer
class, unsigned char* value
IRMAPNRegistry::AddBuf Adds a new property.
IRMAPNRegistry::GetBufByName Retrieves a value using the property name.
IRMAPNRegistry::GetBufById Retrieves a value using the property ID.
IRMAPNRegistry::SetBufByName Sets a value using the property name.
IRMAPNRegistry::SetBufById Sets a value using the property ID.
Integer Reference
Signed integer*, 32-bit value
IRMAPNRegistry::AddIntRef Adds a new property.
Composite
Combination of other properties
IRMAPNRegistry::AddComp Adds a new property.

As you build your monitor plug-in, keep in mind the following about registry datatypes:

Predefined Server Properties

The following table lists the server properties predefined in the RealServer registry.

Predefined Server Registry Properties
Property Name Datatype Description
server Composite RealServer connection statistics.
server.ClientCount Integer Number of clients connected to RealServer.
server.PNAClientCount Integer Number of clients connected using the PNA protocol.
server.RTSPClientCount Integer Number of clients connected using RTSP protocol.
server.HTTPClientCount Integer Number of clients connected using HTTP protocol.
server.UDPTransportCount Integer Number of clients connected using UDP.
server.TCPTransportCount Integer Number of clients connected using TCP.
server.MulticastTransportCount Integer Number of clients connected through Multicast.
server.BandwidthUsage Integer Bandwidth statistics.
server.PercentCPUUsage Integer Current server CPU use (0 through 100 percent).
server.BytesMemoryUsage Integer Number of bytes of memory the server is currently using.
server.Platform String Server operating system.
server.Version String Server software version.

Predefined Client Properties

The following table lists the predefined registry properties for each connected client. The n in the property name is a placeholder for the client's ID. Note that only the client property is present at all times. The client.n.* properties are present only as long as client.n is connected. RealServer deletes these properties from the registry as clients disconnect. Also note that the Session attributes are not available when the client connects, but become available as the client/server control negotiation progresses.

Basic Client Statistics
Property Name Datatype Description
client Composite Client statistics.
client.n Composite Statistics for client.n.
client.n.Addr String IP address of the client computer.
client.n.Bandwidth Integer Connection bandwidth.
client.n.ClientID String Client information, including platform, Player version, and whether client is RealPlayer Plus.
client.n.ConnID Integer Connection ID, which is the same as n (for example, client.54.54).
client.n.GUID String Unique ID of each RealPlayer.
client.n.InterfaceAddr String Server IP address client request came in on.
client.n.isUDP Integer Whether UDP is used. 1=true, 0=false.
client.n.Language String Player's preferred language.
client.n.PlayerStarttime String Player's local time at at start of connection.
client.n.Port Integer Incoming port of RealServer to which the client is connected.
client.n.Protocol String Protocol used by client to connect to RealServer (PNA or RTSP).
client.n.SessionCount String Keeps track of the number of sessions the client has open.
client.n.StartTime String Server's system time at start of client connection.
client.n.SupportMulticast Integer Whether connection supports multicasting. 1=true, 0=false.
client.n.User-Agent String The User-Agent string that the client sent to the server.
client.n.Version String Protocol (PNA or RTSP) version.

Client Session Statistics
Property Name Datatype Description
client.n.Session Composite Client session information.
client.n.Session.n String Statistics for client.n.Session.n.
client.n.Session.n.FileSize Integer Size of the requested file.
client.n.Session.n.LogStats String Client log statistics.
client.n.Session.n.StreamCount Integer Number of client streams.
client.n.Session.n.URL String The URL for this session.
client.n.Session.n.Stream.n Composite Session stream information.
client.n.Session.n.Stream.n.AvgBitRate Integer Stream average bit rate.
client.n.Session.n.Stream.n.Duration Integer Current stream duration in milliseconds.
client.n.Session.n.Stream.n.MimeType String Stream MIME type.
client.n.Session.n.TransportCount Integer Number of transport methods used for session.
client.n.Session.n.Transport.n Composite Client session information for a specific transport type.
client.n.Session.n.Transport.n.
BytesSent
Integer Bytes sent for this transport method.
client.n.Session.n.Transport.n.
ResendFailure
Integer Number of times resend requests were not satisified.
client.n.Session.n.Transport.n.
ResendSuccess
Integer Number of times resend requests were satisfied.
client.n.Session.n.Transport.n.
PacketsSent
Integer Packets sent.
client.n.Session.n.Transport.n.
SendingTime
Integer Time in seconds this transport session has operated.

Predefined License Properties

The following table lists the license properties predefined in the RealServer registry.

Predefined License Properties
Property Name Datatype Description
license Composite License file variables.
license.NumLicenses Integer The number of individual license files that were read in by the server on startup (the number of valid license files in the server's License/ subdirectory).

Predefined Monitor Properties

The following table lists the monitor properties predefined in the RealServer registry.

Predefined Monitor Properties
Property Name Datatype Description
Monitors Composite Information about all connected monitors.
license.NumLicenses Integer The number of monitors currently connected to the server.

Custom or Predefined Server Configuration Properties

In addition to the predefined and user-defined properties described so far, the RealServer Property Registry contains a number of server configuration parameters, which are loaded from a configuration file on server start-up. A plug-in can use the methods listed above to retrieve these customized or predefined RealServer configuration parameters from the registry. (See "Appendix E: RealServer Configuration".) Because the parameters entered in the configuration file do not specify the registry datatypes, RealServer sets the datatypes appropriately as integers or strings when it reads the file. Parameters that have true or false values (case does not matter) are added as integer values with true equal to 1 and false equal to 0. The monitor plug-in then accesses the properties by name according to conventions such as these:


config.Variable_Name
config.List_Name.Variable_Name
config.List_Name.List_Name.Variable_Name

Note
RealServer supports arbitrarily complex nested lists for configuration parameters. The registry property naming conventions may therefore be more complex than the examples above.

Variables within lists and lists within lists can also be accessed by their order within the list one level above them. (They must be accessed this way if they are not named.) Instead of using the variable or list name, the plug-in uses elemx, where x is the list entry number, starting with zero. For example, suppose that the configuration file specifies the following parameter:


<List Name="FSMount">
<List Name="pn-live3">
<Var MountPoint="/live/"/>
<Var Port="7090"/>
</List>
<List Name="pn-local">
<Var MountPoint="/"/>
<Var BasePath="/home/realsystem/rafiles"/>
<Var Authentication="True"/>
</List>
</List>

The plug-in can access the /live/ value for the first MountPoint variable with any of the following:


config.FSMount.pn-live3.MountPoint 
config.FSMount.pn-live3.elem0
config.FSMount.elem0.MountPoint
config.FSMount.elem0.elem0


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