StartProfile

Article
06/26/2007

The StartProfile function sets the counter to 1 (on) for the specified profiling level.

PROFILE_COMMAND_STATUS PROFILERAPI StartProfile(
                       PROFILE_CONTROL_LEVEL Level, 
                       unsigned int dwId);

Parameters

Level

Indicates the profile level to which performance data collection can be applied. The following PROFILE_CONTROL_LEVEL enumerators can be used to indicate one of the three levels to which performance data collection can be applied:

Enumerator	Description
PROFILE_GLOBALLEVEL	Global level setting affects all processes and threads in the profiling run.
PROFILE_PROCESSLEVEL	Process level setting affects all threads that are part of specified process.
PROFILE_THREADLEVEL	Thread profiling Level setting affects the specified thread.

dwId

The process or thread identifier generated by the system.

Property Value/Return Value

The function indicates success or failure by using PROFILE_COMMAND_STATUS enumeration. The return value can be one of the following:

Enumerator	Description
PROFILE_ERROR_ID_NOEXIST	The profiling element ID does not exist.
PROFILE_ERROR_LEVEL_NOEXIST	The profiling level specified does not exist.
PROFILE_ERROR_MODE_NEVER	The profiling mode was set to NEVER when the function was called.
PROFILE_ERROR_NOT_YET_IMPLEMENTED	The profiling function call, profiling level, or combination of call and level is not yet implemented.
PROFILE_OK	The call was successful.

Remarks

StartProfile and StopProfile control the Start/Stop state for the profiling level. The default value of Start/Stop is 1. The initial value can be changed in the registry. Each call to StartProfile sets Start/Stop to 1; each call to StopProfile sets it to 0.

When the Start/Stop is greater than 0, the Start/Stop state for the level is ON. When it is less than or equal to 0, the Start/Stop state is OFF.

When the Start/Stop state and the Suspend/Resume state are both ON, the profiling state for the level is ON. For a thread to be profiled, the global, process, and thread level states for the thread must be ON.

.NET Framework Equivalent

Microsoft.VisualStudio.Profiler.dll

Function Information

Header: Declared in VSPerf.h

Import library: VSPerf.lib

Example

The following example illustrates the StartProfile function call.

void ExerciseStartProfile()
{
    // StartProfile and StopProfile control the
    // Start/Stop state for the profiling level. 
    // The default initial value of Start/Stop is 1. 
    // The initial value can be changed in the registry. 
    // Each call to StartProfile sets Start/Stop to 1; 
    // each call to StopProfile sets it to 0. 
    
    // Variables used to print output.
    HRESULT hResult;
    TCHAR tchBuffer[256];

    // Declare enumeration to hold return value of 
    // the call to StartProfile.
    PROFILE_COMMAND_STATUS profileResult;

    profileResult = StartProfile(
        PROFILE_THREADLEVEL,
        PROFILE_CURRENTID);

    // Format and print result.
    LPCTSTR pszFormat = TEXT("%s %d.\0");
    TCHAR* pszTxt = TEXT("StartProfile returned");
    hResult = StringCchPrintf(tchBuffer, 256, pszFormat, 
        pszTxt, profileResult);

#ifdef DEBUG
    OutputDebugString(tchBuffer);
#endif
}