StartProfile
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
The StartProfile function sets the counter to 1 (on) for the specified profiling level.
Syntax
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
}