Client Logging (Microsoft Media Foundation)
The network source supports client logging, which provides a way for the media server to track the activity of the clients that connect to it. Client logs enable a server to record connection, rendering, and streaming statistics. These logs can be used by content providers in various scenarios, such as, to trace media server usage and generate billing, or to deliver suitable-quality content depending on the speed of the client's network.
A log file contains several client event entries. Each log entry contains a number of space-delimited fields. There are two types of client logs: rendering (playing) and streaming (receiving). Because content can be played and streamed simultaneously, the client can send a combination of both types of log data. In certain cases, two log entries can exist for the same session. For example, when Fast Cache is enabled, the client can finish receiving the streamed content before it finishes rendering it. In that case, the streaming log data would be sent before the rendering log data.
The client sends rendering log data to the server when the client changes from any playing state (play, fast-forward, or rewind) to a non-playing state (stop, pause, end of stream, and beginning of stream). When data for a rendering log is submitted, a connection is made directly to the media server or a configured proxy server.
If the content is stored in a temporary local cache file on the computer that is running the client, the client can read a file from its local cache and submit the rendering log data to indicate that it has played the content. In this case, the client reads a file from its local cache, the rendering log entry does not contain any network statistics, and the protocol is set to Cache.
The client sends streaming log data to the server to indicate how the client received the content, but not how it was rendered. The client can send the streaming log long before the client finishes rendering the content.
This topic does not provide information about all the log fields. For a complete reference, see Windows Media Log Data Structure.
Configuring Log Fields
Media Foundation enables the client to configure the network source by using properties. The application must set the appropriate properties in a property store and pass it to one of the source resolver methods. The source resolver creates the network source as requested and opens a connection with the server. If the connection is successful, the client sends information about itself.
The following table describes the log fields and the corresponding properties that an application can set through the source resolver. This information does not change during the session.
| Logging field | Description |
|---|---|
| c-playerid | Unique identification of the player. This information is sent at the beginning of the connection. Typically, this is a GUID of the client. The client can send this information to the server in the MFNETSOURCE_PLAYERID property. The client sends this information to the server at the beginning of the connection. Sample value: "{c579d042-cecc-11d1-bb31-00a0c9603954}" |
| c-playerversion | The version number of the player that is sent at the beginning of the connection. The client can send this information to the server in the MFNETSOURCE_PLAYERVERSION property. The client sends this information to the server at the beginning of the connection. |
| cs(User-Agent) | Browser type used if the player was embedded in a browser. This value can be set by the client in the MFNETSOURCE_BROWSERUSERAGENT property. If the player was not embedded, this field refers to the user agent of the client that generated the log. In this case, the client must set the MFNETSOURCE_PLAYERUSERAGENT property. The client sends this information to the server at the beginning of the connection. Sample value: "Mozilla/4.0_(compatible;_MSIE_4.01;_Windows_98)" |
| cs(Referer) | URL of the webpage in which the player was embedded (if it was embedded). The client can send this information to the server in the MFNETSOURCE_BROWSERWEBPAGE property. The client sends this information to the server at the end of the connection. Sample value: "https://www.example.microsoft.com" |
| c-hostexe | For player log entries, the host program (.exe) that was run. For example, a webpage in a browser, a Microsoft Visual Basic applet, or a stand-alone player. The client can send this information to the server in the MFNETSOURCE_HOSTEXE property. The client sends this information to the server at the end of the connection. Sample values:
|
| c-hostexever | Host program (.exe) version number. The client can send this information to the server in the MFNETSOURCE_HOSTVERSION property. The client sends this information to the server at the end of the connection. |
The following code example shows how a client application configures the network source. This example sets the "c-hostexe" log field.
// Creates a media source from a URL.
//
// This example demonstrates how to set the MFNETSOURCE_HOSTEXE
// configuration property on the network source.
HRESULT CreateMediaSourceWithLogParams(
PCWSTR pszURL,
IMFMediaSource **ppSource
)
{
IPropertyStore *pConfig = NULL;
// Configure the property store.
HRESULT hr = PSCreateMemoryPropertyStore(IID_PPV_ARGS(&pConfig));
if (SUCCEEDED(hr))
{
PROPERTYKEY key;
key.fmtid = MFNETSOURCE_HOSTEXE;
key.pid = 0;
PROPVARIANT var;
var.vt = VT_LPWSTR;
var.pwszVal = L"MyPlayer.exe";
hr = pConfig->SetValue(key, var);
}
// Create the source media source.
if (SUCCEEDED(hr))
{
hr = CreateMediaSource(pszURL, pConfig, ppSource);
}
SafeRelease(&pConfig);
return hr;
}
Retrieving Network Statistics
When the application calls one of the source resolver methods, it creates the network source, sets the properties specified in the property store, and opens a session with the media server. In addition to the configurable information described in the previous section, additional data is transferred between the server and the client at the beginning of the session, during streaming, and when the session is closed.
The application can retrieve network statistics by using the MFNETSOURCE_STATISTICS_SERVICE service identifier. To use this service, the application can call the MFGetService function to get the property store that contains network statistics in the MFNETSOURCE_STATISTICS property. Specific values can be retrieved by providing the corresponding identifier defined in the MFNETSOURCE_STATISTICS_IDS enumeration.
The following code example shows how to use the service to get the number of packets received by the client.
HRESULT GetPacketsReceived(IMFMediaSession *pSession, DWORD *pcPackets)
{
IPropertyStore *pProp = NULL;
PROPVARIANT var;
// Get the property store from the media session.
HRESULT hr = MFGetService(
pSession,
MFNETSOURCE_STATISTICS_SERVICE,
IID_PPV_ARGS(&pProp)
);
// Get the number of packets received by the client.
if (SUCCEEDED(hr))
{
PROPERTYKEY key;
key.fmtid = MFNETSOURCE_STATISTICS;
key.pid = MFNETSOURCE_RECVPACKETS_ID;
hr = pProp->GetValue(key, &var);
}
if (SUCCEEDED(hr))
{
*pcPackets = var.lVal;
}
PropVariantClear(&var);
SafeRelease(&pProp);
return hr;
}
The following list describes some of the network statistics identifiers defined in MFNETSOURCE_STATISTICS_IDS.
| Network statistics identifier | Description |
|---|---|
| MFNETSOURCE_AVGBANDWIDTHBPS_ID | Average bandwidth (in bits per second) at which the client was connected to the server. The value is calculated across the entire duration of the connection. |
| MFNETSOURCE_BUFFERINGCOUNT_ID | Number of times the client buffered while playing the stream. |
| MFNETSOURCE_BYTESRECEIVED_ID | Number of bytes received by the client from the server. The value does not include any overhead that is added by the network stack. The same content streamed by using different protocols can result in different values. |
| MFNETSOURCE_LINKBANDWIDTH_ID | Maximum available bandwidth of the client in bits per second. |
| MFNETSOURCE_LOSTPACKETS_ID | Number of packets sent by the server but lost during transmission, and never played by the client. The value does not include TCP or UDP packets. |
| MFNETSOURCE_RECVPACKETS_ID | Number of packets received from the server The value does not include TCP or UDP packets. |
| MFNETSOURCE_RECOVEREDBYECCPACKETS_ID | Packets lost in the network that were repaired and recovered at the client layer. This value does not include TCP or UDP packets. |
| MFNETSOURCE_RESENDSREQUESTED_ID | The number of requests made by the client to receive new packets. This value does not include TCP or UDP packets. |
| MFNETSOURCE_RECOVEREDPACKETS_ID | Number of packets recovered because they were resent through UDP. This value does not include TCP or UDP packets. This field contains a zero unless the client is using UDP resend. |
| MFNETSOURCE_BUFFERPROGRESS_ID | The percentage of the playout buffer filled during buffering. |
| MFNETSOURCE_PROTOCOL_ID | Protocol used to access the stream. This may differ from the protocol requested by the client. |
| MFNETSOURCE_TRANSPORT_ID | Transport protocol used to deliver the stream. This must be either UDP or TCP. |