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.

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.

Related topics

Network Source Features

Networking in Media Foundation