RTC Client API v1.2 SDK

 

Table Of Contents

Introduction. 2

How to use RTC Client API v1.2 SDK.. 2

How to build your own application. 3

How to compile and run the RTC Client API v1.2 samples. 3

How to enable RTC API policies. 4

How to capture SIP messages. 5

How to use RTC API in a multithreaded application. 5

How to create a Manifest for Your Application. 5

Using the side-by-side RTC Client API DLLs in managed code. 7

Introduction. 7

Solution. 7

Requirements. 7

Creating the interop assembly. 8

Troubleshooting. 8

1. I get a runtime error “The system cannot execute the specified program” while trying the samples. 8

2. I get a runtime error E_NOINTERFACE while trying the samples. 8

3. I get a compile time error “Can not find rtccore.h”. 9

4. I get a compile time error “Undefined interface IRTCClient2”. 9

5. I get error “RTC Client V1.1 or higher required!” while trying rtcsample. 9

6. I have installed RtcApiSetup.exe and can run samples, but I still get a runtime error “The system cannot execute the specified program” while trying my own applications. 9

7. I get an error code, how do I find out its meaning?. 11

8. How do I enable tracing?. 12

 


 

 

Introduction

 

The Real-time Communications (RTC) Client API is a set of COM interfaces and methods designed to create PC-PC, PC-phone, phone-phone audio/video calls, or text-only Instant Messaging (IM) sessions over the Internet.  The API also allows to:

·       Add application and whiteboard sharing to a  PC-to-PC session.

·       Use presence information to track the location of contacts for communication purposes.

RTC Client API V1.2 has implemented a number of fundamental changes to V1.0 in order to support roaming and logical grouping functionality, as well as user search behaviors.

The modules implementing RTC V1.2 API together with code-samples are packaged in an MSI installer RtcApiSdk.msi

 

This is the tree structure of the installer.

 

<system drive>:\Program files\RTC Client API v1.2 SDK

├───HELP\RTCCLNT.CHM                SDK Online Help

├───INSTALLATION
         
EXAMPLE.EXE.MANIFEST  Template of a manifest file that your application should include.

          RtcApiSetup.exe                       An MSI setup file which installs rtcclnt.msm. You must run it before using the samples.

   └───MergeModules                        RtcClnt.msm includes all the RTC libraries for all supported OS platforms. Included are 26 languages with locale ID as the subdirectory name. Check here for locale IDs.

└───SDK

    ├───IDL\RtcCore.idl                         IDL file

    ├───INC                                          Include directory. It should be listed early the INCLUDE environment variable.

    └───Samples

        ├───CallControl                  C++ sample for audio/video Hold, Transfer, and Forward.

        ├───CustomSDP                 C++ sample for handling session negotiations.

        ├───RTCIncoming                       C++ sample for receiving calls.

        ├───RTCOutgoing              C++ sample for making calls.

        ├───RtcPresence                 C# sample for Registering, Roaming, handling Buddies and Watchers.

        ├───RTCSAMPLE                     C++ sample for RTC apps (this is the most complete sample from those provided in the package)

        └───VBSAMPLE                       Visual Basic 6 sample.

 

How to use RTC Client API v1.2 SDK

How to build your own application

 

After trying out the samples and reading through the HELP\RtcClnt.chm, you are ready to create your own application. Please, pay attention to the following two items:

  1. Creating a manifest file and include it in your application.
  2. Creating a Windows Installer package to include RtcClnt.msm and your application files.

 

The RtcClnt.msm merge-module includes all binaries and installation instructions needed to install the RTC Client API v1.2 as part of a Windows Installer setup. The merge-module supports the following OS platforms:

·        Windows 98

·        Windows Me

·        Windows 2000

·        Windows XP

 

The RtcClnt.msm merge-module also handles operating system upgrades gracefully. For example, you install RTC App on Windows 2000. After some time, you upgrade the OS to Windows XP. Later you upgrade the OS to XP SP1. Your RTC App will work for all the time.

 

  The RTC V1.2 API DLLs installed by the merge-module should not be registered with regsvr32.exe.

 
For information on how to use merge modules within a Windows Installer, see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msi/setup/merge_modules.asp

 

How to compile and run the RTC Client API v1.2 samples

 

  1. Install the Windows platform SDK
    In order to compile and run the sample programs, you must have the SDK installed on your computer, or have Visual Studio C++ .NET installed. You can download the SDK from http://www.microsoft.com/msdownload/platformsdk/sdkupdate/default.htm

            Follow Core SDK à Install this SDK à Continue à Accept, and then install the
            SDK.
            Click Install SDK with Visual Studio for more information.

  1. Run RtcApiSDK.msi

Verify that “%ProgramFiles%\RTC Client API v1.2 SDK” directory is created

  1. Run % ProgramFiles%\RTC Client API v1.2 SDK\Installation\RtcApiSetup.exe.
    This Windows Installer setup package installs RTC Client API v1.2 on a machine that is used for development. It installs the merge module onto the computer, and allows the Side-by-Side RTC Client API v1.2 DLLs to be used on the machine.
    Installing the package is essential to obtain and use the samples included within the RtcApiSdk.msi.

  1. If you are using Visual Studio,  Redirect INCLUDE and LIB path

Make sure the SDK include directory is listed before the Visual C++ include directory.

       IMPORTANT: Add %ProgramFiles%\RTC Client API v1.2 SDK\SDK\inc before all other directories.

Make sure the SDK lib directory is listed before the Visual C++ lib directory. For command-line builds, check the LIB environment variable using the SET command. For builds within Visual Studio, you must update the directory settings.

  1. To compile samples in an SDK window, click Start Button à Programs à Microsoft Platform SDK à Open build environment window à XP 32 build environment; then type NMake in the "Microsoft Platform SDK Windows XP 32-bit" command window,

 

  1. Two samples, RtcIncoming and RtcOutgoing, use an internal resource manifest (the recommended way of using a manifest file).
    Other samples use external manifest files. For those samples, you must copy the manifest file to the same directory as the .EXE file.

  2.  If you get errors while following the above instructions, please refer to the Troubleshooting section.

 

How to enable RTC API policies

There are two RTC API policies: PortRange and MaxAudioVideoBitrate.

 

Example of setting these two policies:

REGEDIT4
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\RTC]
"MaxAudioVideoBitrate"=dword:000320c8
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows\RTC\PortRange]
"Enabled"=dword:00000001
"MinSipDynamicPort"=dword:00001bbc
"MaxSipDynamicPort"=dword:00001bbf
"MinMediaPort"=dword:000014e6
"MaxMediaPort"=dword:000014e9

 

PortRange

Specifies the ranges of dynamically-allocated ports that the RTC Client API v1.2 can use to transmit signaling data using SIP and to transmit audio and video data using RTP. If you open specific ranges of ports on a firewall between two clients to allow the clients to communicate, this policy forces the clients to use ports in those ranges. If you do not configure this policy setting, RTC Client API v1.2 attempts to send and receive SIP and RTP data using ports selected at random throughout the range of 1024 to 65535 inclusive.

 

     NOTE: If you enable this policy setting, do not create SIP and RTP port ranges that overlap.

 

When this policy is enabled, both ranges must fall between 1024 and 65535 inclusive. In each range the following conditions must be met:

·     The MinSipDynamicPort must be less than the MaxSipDynamicPort,

·     The SIP range must contain at least two ports,

·     The RTP range must contain at least four ports (if the lowest port number in the range is even) or five ports (if the lowest port number in the range is odd).

 If you specify a range that violates one of these rules, your application’s attempt to create an instance of the RTC Client API v1.2 will fail.

 

MaxAudioVideoBitRate

Limits bandwidth that RTC API applications can use for audio and video calls. If you do not configure this policy setting, RTC API applications use as much bandwidth as is available and necessary for audio and video calls.

How to capture SIP messages

There are two ways to capture SIP messages:

·       Using Network Monitor

·       Using RtcDll tracing mechanism. To use this method obtain Rtcdll traces. Then search for “End of Sending Packet” and “End of Data Received” in the RtcDll0.log.

How to use RTC API in a multithreaded application

RTC Client is a STA COM object and uses Message Loop for function calls and event processing. In V1.2, you must create the RTC Client COM Object in a STA thread and invoke RTC Client APIs on the same STA thread.

How to create a Manifest for Your Application

For applications that use RTC Client API v1.2 on a computer running Windows XP, you must create an application manifest and deploy it with your application. For more information on using Side by Side assemblies, and Side by Side in general, please see Isolated Applications and Side-by-side Assemblies.

To create a manifest for your application

1.      Copy this sample manifest and paste it into any text editor. Or simply copy the template file from “%ProgramFiles%\RTC Client API v1.2 SDK\Installation\EXAMPLE.EXE.MANIFEST

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<!-- Copyright 1981-2003 Microsoft Corporation -->

<assembly

    xmlns="urn:schemas-microsoft-com:asm.v1"

    manifestVersion="1.0">

 

    <assemblyIdentity

        version="1.0.0.0"

        processorArchitecture="x86"

        name="YourApplicationName"

        type="win32"

    />

 

    <description>Sample RTC Application</description>

 

    <dependency>

        <dependentAssembly>

            <assemblyIdentity

                type="win32"

                name="Microsoft.Windows.Networking.RtcDll"

                version="5.2.2.1"

                processorArchitecture="X86"

                publicKeyToken="6595b64144ccf1df"

                language="*"

            />

        </dependentAssembly>

    </dependency>

</assembly>

 

2.       After you have pasted the sample code above, you must update it as appropriate for your application. See Assembly Manifests in MSDN.

3.      Update the description for your application.

The <description> element is optional, so you can either update its contents to include a brief description of your application or remove it from your manifest code. If you choose to remove it, be sure to remove both its opening and closing tags and any character data contained within them.

4.        For the dependent assembly section, update the featured attribute values for the <assemblyIdentity> element so that its values are appropriate to the version of RTC Client API. For V1.2 release the version attribute is 5.2.2.1.

5.        Decide how to package and deploy your application manifest with your application. You can use the manifest as an internal resource, or as an external file. To include the application manifest directly in the resources for your application, add the following line to the resource (.rc) file:

CREATEPROCESS_MANIFEST_RESOURCE_ID RT_MANIFEST "YourApp.exe.manifest"

Or simply like Samples\RTCIncoming\res\RTCIncoming.rc2:

1  RT_MANIFEST  "YourApp.exe.manifest"

Be sure you update "YourApp.exe.manifest" with the name for your manifest file. After you add the line above to your application .rc file, the manifest will be directly included with your application binary file the next time it is compiled.

If you do not choose to include the manifest in this way, include the manifest file separately in the Windows Installer package (.msi) you create to install your application.

6.       Decide how to package and deploy your application manifest with your application. Save the application manifest to file in the same directory as the executable file for your application. Name your manifest file so that it has the same name as your application, and add the ".manifest" extension to the end of it. For example, if your application executable is called YourApp.exe, the manifest file should be named YourApp.exe.manifest.

Note   If you provide your manifest both separately (externally) and internally in the resource section of your compiled executable, the file system version of your manifest will take precedence over the one included with the executable file in XP and XP SP1. But the internal resource manifest will take precedence in .net server.

7.      Test your application to ensure that you get the results you want. Be sure that your test computer does not already have the side-by-side assembly for RTC Client API v1.2 registered on it. Otherwise, your testing will be compromised and the results will be incorrect.

8.      Deploy or update your application as a Windows Installer package, merge the RTCCLNT.MSM with your setup package.

Using the side-by-side RTC Client API DLLs in managed code

Introduction

To enable interoperability between managed code and COM the .NET Framework provides a utility TLBIMP.EXE that generates so called interop DLLs, which expose COM objects as classes and interfaces directly usable from any language supporting the .NET Framework.

 

The default behavior of the generated interop DLL is to load the registered COM object whenever a client application creates an instance of the managed class. This presents problems when the application is in fact trying to use the components exposed by the SxS DLLs.

Solution

The following procedure outlines the steps required to enable the application using the interop assembly to load the Side-by-Side components and not the registered ones.

Requirements

The steps outlined below only work with .NET Frameworks version 1.1 and above on Windows XP SP1 or Windows Server 2003 and above. At the time this document is written a beta version of .NET Frameworks version 1.1 is available for public download at http://msdn.microsoft.com/netframework/productinfo/v1.1/default.asp

Creating the interop assembly

The following steps are required to create an interop assembly that will expose the RTC Client API to managed applications:

  1. [Optional, if signing the interop assembly] Create a public/private key pair to sign the interop assembly using SN.EXE;

sn –k keypair.snk

  1. Run TLBIMP.EXE to create the interop assembly. Optionally use the /keyfile  option with the key pair created in the previous step to sign the interop assembly;

tlbimp rtcdll.dll /keyfile:keypair.snk

  1. Create a Side-by-Side application manifest for the application using the interop assembly (see the manifest creation section above).

 

Troubleshooting

1. I get a runtime error “The system cannot execute the specified program” while trying the samples.

 Before running the samples, please run “%ProgramFiles%\RTC Client API v1.2 SDK\Installation\RtcApiSetup.exe”. This ensures that the RTC Client API v1.2 binaries are correctly installed on your development machine.

2. I get a runtime error E_NOINTERFACE while trying the samples.

 This error can only occur on Windows XP and above. It indicates that your manifest file does not take effect because your application is loading RtcDll.dll from %WinDir%\System32, which is RTC Client API V1.0 on XP, or that you don’t have a manifest file at all.

 

To solve the problem:

   -- Make sure you do have a manifest

   -- If you are using an internal resource manifest, please verify the manifest file name is correctly specified in the .rc file.

   -- If you are using an external manifest, copy the manifest to the same directory as the .exe file. These samples use external manifest: CallControl, CustomSDP, RtcPresence, RTCSAMPLE, and VBSAMPLE. If you create your own manifest, please verify that the manifest has the same prefix as the .exe file.

3. I get a compile time error “Can not find rtccore.h”.

   You have not installed Windows SDK, or have not redirected the INCLUDE directory. See “How to compile and run RTC Client API v1.2 samples

4. I get a compile time error “Undefined interface IRTCClient2”.

You should add %ProgramFiles%\RTC Client API v1.2 SDK\SDK\inc to the top of the INCLUDE directories.

    Try to compile the following program. If you cannot compile it, please read  “How to compile and run the RTC Client API v1.2 samples” section again.

#include <stdio.h>
#include <rtccore.h>
IRTCClient2 *g_pClient=NULL;
int __cdecl main(int argc, char* argv[])
{
    printf("Hello, RTC!\n");
    return 0;
}

 

5. I get error “RTC Client V1.1 or higher required!” while trying rtcsample.

Since RtcSample uses external manifest file, you must copy the RtcSample.exe.manifest to the directory where the executable is.  Without a manifest file, your app will load %WinDir%\system32\RtcDll.dll, which does not support interface IRTCClient2.

 

Another indication of missing manifest file is getting error E_NOTIMPL(0x80004001) when calling IRTCProfile::GetProfile() which is only implemented in V1.2.

 

6. I have installed RtcApiSetup.exe and can run samples, but I still get a runtime error “The system cannot execute the specified program” while trying my own applications.

   First, you should check system events by running %WinDir%\System32\EventVwr.exe

 

               Event Viewer(Local)

       |__ Application

       |__ Security

       +__ System   <------------------ Click here

 

If you see any error messages with SideBySide in the source field, it means that there are some problems with your manifest. Most common errors are XML syntax errors in yourapp.exe.manifest file, and the assembly version number in your manifest not being equal to the one installed on your computer.

 

The assembly version for V1.2 RTM is 5.2.2.1, for V1.2 RC1 it is 5.2.1.0000, for V1.2 Beta it is 5.1.0.0

You can check what assembly version you have installed on your computer by typing:

 

               dir %WinDir%\WinSxS\*rtc*

 

-- The installed assembly version number is 5.1.0.0 if you see:

x86_Microsoft.Windows.Networking.RtcDll_6595b64144ccf1df_5.1.0.0_x-ww_91d50d8f

              

-- The installed assembly version number is 5.2.1.0000 if you see:

x86_Microsoft.Windows.Networking.RtcDll_6595b64144ccf1df_5.2.1.0000_x-ww_09834345

 

-- The installed assembly version number is 5.2.2.1 if you see:       x86_Microsoft.Windows.Networking.RtcDll_6595b64144ccf1df_5.2.2.1_x-ww_d6bd8b93

 

If no results were produced by running the above dir command, then RTC Client API v1.2 was not successfully installed on your computer.

To solve the problem, either re-run RtcApiSetup.exe,or build your own installer using RtcClnt.msm and install RTC libraries using the installer.

 

         If you can not compile and run the following program, please read the section “How to compile and run the RTC Client API v1.2 samples . The most common mistake is to forget the manifest and as a result getting error 0x80004002 (E_NOINTERFACE).

 
#include <stdio.h>
#include <windows.h>
#include <rtccore.h>
 
IRTCClient2 *g_pClient=NULL;
int __cdecl main(int argc, char* argv[])
{
    HRESULT hr = E_FAIL;
 
    // initialize COM.
    hr =  CoInitialize(NULL);
    if ( FAILED(hr) ){
       printf(“CoInitialize failed:hr=%x\n”, hr);
       return -1;
       }
 
    printf("CoInitialize succeeded!\n");
    // Create the RTC client
    hr = CoCreateInstance(
        __uuidof(RTCClient),
        NULL,
        CLSCTX_INPROC_SERVER,
        __uuidof(IRTCClient2),
        (LPVOID *)&g_pClient
        );
 
    if (FAILED(hr)){
        printf("CoCreateInstance failed: hr=%x\n", hr);
        return -2;
        }
    printf("Hello, RTC!\n");
    g_pClient->Release();
    CoUninitialize();
    return 0;
}

 

7. I get an error code, how do I find out its meaning?

    The RTC API error codes are defined in %ProgramFiles%\RTC Client API v1.2 SDK\Sdk\Inc\RtcErr.h

    In your program, you can call FormatMessage() to get the description of that error code:

void PrintRtcError(char * szMsg, HRESULT StatusCode)
{
    PWSTR   pErrorText=NULL;   
    HANDLE  hRTCModule = GetModuleHandleW(L"RtcDll.dll");
    //call GetModuleHandleW(L"RtcRes.dll") for localized error strings
    if( hRTCModule )
        ::FormatMessageW(
            FORMAT_MESSAGE_ALLOCATE_BUFFER |
            FORMAT_MESSAGE_FROM_HMODULE |
            FORMAT_MESSAGE_IGNORE_INSERTS,
            hRTCModule,
            StatusCode,
            0,
            (LPWSTR)&pErrorText,
            0,
            NULL
            );
 
    if(pErrorText)
        printf("%s - %x, reason=%ls\n", szMsg, StatusCode, pErrorText);
    else
    {
        // check if it is system error
        ::FormatMessageW(
            FORMAT_MESSAGE_ALLOCATE_BUFFER |
            FORMAT_MESSAGE_FROM_SYSTEM,
            NULL,
            StatusCode,
            0,
            (LPWSTR)&pErrorText, 
            0,
            NULL);
        
        if( pErrorText )
            printf("%s - %x, reason[system]=%ls\n", szMsg, StatusCode, pErrorText);
        else
            printf("%s -error=%x. Can not load error strings!!\n", szMsg, StatusCode);
    }
    
    if(pErrorText) LocalFree(pErrorText);
}
 
HANDLE  hRTCModule = GetModuleHandleW(L"RtcRes.dll");
PWSTR   pErrorText;
::FormatMessageW(
 FORMAT_MESSAGE_ALLOCATE_BUFFER |
        FORMAT_MESSAGE_FROM_HMODULE |
        FORMAT_MESSAGE_IGNORE_INSERTS,
        hRTCModule,
        StatusCode,
        0,
        (LPWSTR)&pErrorText,
        0,
        NULL
        );
 

8. How do I enable tracing?

There are three DLL files, RtcDll, DxmRtp, and RtcRtp, in RTC Client API 1.2. Here is a table for their purpose and the location of the registry key that controls tracing from a DLL.

 

Filename

Purpose

RegKey name

DxmRtp.dll

XP and above streaming support

HKCU\SOFTWARE\Microsoft\Tracing\DxmRtp

RtcDll.dll

API and SIP stack

HKCU\SOFTWARE\Microsoft\Tracing\RtcDll

RtcRtp.dll

Win2k and below streaming support

HKCU\SOFTWARE\Microsoft\Tracing\RtcRtp

 

 

If you don’t want to read through the whole section, you can simply save the contents of the below frame into a .reg file, and load it into your computer. Then, after running RTC API samples, you will find tracing files c:\RtcDll0.log and c:\DxmRtp*.log. (On Windows 2000, the latter will be c:\RtcRtcp*.log)

 
 
REGEDIT4
 
[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Tracing\RTCDLL]
"EnableFileTracing"=dword:00000001
"EnableConsoleTracing"=dword:00000000
"FileTracingMask"=dword:0fff0000
"ConsoleTracingMask"=dword:00070000
"MaxFileSize"=dword:01000000
"FileDirectory"="c:\\"
"EnableDebuggerTracing"=dword:00000001
"AdvancedOptions"=dword:00000002
"DebuggerTracingMask"=dword:000f0000
"MaxFiles"=dword:00000001
 
[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Tracing\DXMRTP]
"EnableFileTracing"=dword:00000001
"EnableConsoleTracing"=dword:00000000
"FileTracingMask"=dword:0fff0000
"ConsoleTracingMask"=dword:00070000
"MaxFileSize"=dword:01000000
"FileDirectory"="c:\\"
"EnableDebuggerTracing"=dword:00000001
"AdvancedOptions"=dword:00000006
"DebuggerTracingMask"=dword:000f0000
"MaxFiles"=dword:00000001
 

 

 

If you want to find out the meanings of each field in the registry, keep reading. The below examples will use RTCDLL.

 

RTC API supports three kind of tracing: File, Console, and Debugger. Let’s assume the current registry entry for RTCDLL looks like this:

 

HKEY_CURRENT_USER\Software\Microsoft\Tracing\RTCDLL

    AdvancedOptions = REG_DWORD 0x00000004

    EnableFileTracing = REG_DWORD 0x00000001

    EnableConsoleTracing = REG_DWORD 0x00000000

    EnableDebuggerTracing = REG_DWORD 0x00000000

    FileTracingMask = REG_DWORD 0xffff0000

    ConsoleTracingMask = REG_DWORD 0xffff0000

    DebuggerTracingMask = REG_DWORD 0xffff0000

    MaxFileSize = REG_DWORD 0x01000000

    MaxFiles = REG_DWORD 0x00000002

    FileDirectory = REG_EXPAND_SZ %systemdrive%\Tracing

 

To enable logs in the simplest way, just set to 1 the values of the outputs you want to use, e.g. to enable the debugger tracing output set:

 

    EnableDebuggerTracing = REG_DWORD 0x00000001

 

and similarly for File and Console tracing.

 

Now, if you desire to achieve more control, then you need to modify the values in the corresponding mask, i.e. for the example above, you need to select what bits to set in DebuggerTracingMask.

 

By default, the tracing masks enable ALL the categories. The higher 16 bits in the mask are used to select the particular category (e.g. ERROR, WARN, etc.) you desire to log, which can be independently enabled. For example, you could enable only the WARN category but not to use at all the others.

 

The currently defined categories are:

 

    ERROR                = 0x00020000 Errors

    WARN                 = 0x00040000 Warnings

    INFO                 = 0x00080000 Informational

    TRACE                = 0x00100000 Enter/exit function

    REF                  = 0x00200000 Reference count

 

    GRAPHEVENT           = 0x00400000 Graph events

    MEDIAEVENT           = 0x00800000 Media events

    MEDIAQUALITY         = 0x01000000 Media quality

 

E.g. if you would like to log into the console, use only the ERROR and WARN categories, but the same plus TRACE and REF categories to a file, and no debugger output at all, then the relevant registry entries would be changed to look like this:

 

    EnableFileTracing = REG_DWORD 0x00000001

    EnableConsoleTracing = REG_DWORD 0x00000001

    EnableDebuggerTracing = REG_DWORD 0x00000000

    FileTracingMask = REG_DWORD 0x00360000

    ConsoleTracingMask = REG_DWORD 0x00060000

    DebuggerTracingMask = REG_DWORD 0xffff0000

 

NOTE:

DebuggerTracingMask was unchanged as its value does not matter because any log output is disabled for it.

 

In the following sections you will find additional details.

 

What are the defaults?

 

    0,           /* AdvancedOptions */

 

    0,           /* EnableFileTracing */

    0,           /* EnableConsoleTracing */

    0,           /* EnableDebuggerTracing */

   

    0xffff0000,  /* FileTracingMask */

    0xffff0000,  /* ConsoleTracingMask */

    0xffff0000,  /* DebuggerTracingMask */

 

    0x800000,    /* MaxFileSize */

    2,           /* MaxFiles */

    "%USERPROFILE%\Tracing",  /* FileDirectory */

 

What are the AdvancedOptions?

 

TRACE_NO_STDINFO 0x0001

Used to prevent the output of the STDINFO (i.e. time, process and thread ID, index, or any future addition).

 

TRACE_USERECORD  0x0004

Used to print the record index (i.e. a sequence number each log has) as part of the STDINFO.

 

TRACE_ DOUBLETIME 0x0008

Print time as dddddd.dddddd instead of the default hh:mm:ss.ms

 

TRACE_USE_MODULE 0x0020

Print the module name in STDINFO, e.g. “DxmRtp_Rtp”.

In addition, the upper 16 bits of AdvancedOptions can be used to call DebugBreak() whenever the corresponding log category is printed, for that you don’t need to actually have any logging enabled, it would still work.

 

E.g. let’s say that you want DebugBreak() to be called on each ERROR category log printed, then, knowing that ERROR category mask is 0x00020000, you just need to set the mask 0x00020000 (bit 17) in the AdvancedOptions value.

 

This can be very useful ONLY if each developer leaves as an error what is really an error (i.e. something that should never happen and if it does it needs to be investigated), today, I’ve seen error logs that should be just warnings. To do the same with say category WARN, just set bit mask 0x00040000 (bit 18) in this registry value.

 

What is MaxFiles?

 

This parameter can be [1,10], and is the maximum number of files that will be created, files created are numbered RTCDLL0.log, RTCDLL1.log, etc, whenever index MaxFiles-1 is reached, the file with index 0 is deleted, all the other files are renamed and the new file with index MaxFiles-1 is created, so the most recent logs are always in the highest index.

 

E.g. if MaxFiles = 5, then after file RTCDLL0.log is full, RTCDLL1.log will be created and so on until RTCDLL4.log is full, then RTCDLL0.log will be deleted, RTCDLL1.log will be renamed as RTCDLL0.log, RTCDLL2.log renamed as RTCDLL1.log, and so on until RTCDLL4.log is renamed as RTCDLL3.log and a new file RTCDLL4.log is created, so the latest logs from that point forward will always be sent to RTCDLL4.log.

 

A next file (current index + 1) will be created whenever the file size is above or equal to MaxFileSize after the log being printed.

 

If MaxFiles is set with a value out of the allowed range [1,10], internally it will be capped.