NameProfile

Článek
03/04/2013

Funkce NameProfile přiřazuje řetězec určenému procesu či vláknu.

Aplikační rozhraní NameProfile je dostupné pouze pro profilování instrumentace.Aplikační rozhraní NameProfile není pro profilování odběrem vzorků podporováno.

PROFILE_COMMAND_STATUS PROFILERAPI NameProfile(
                                   LPCTSTR pszName, 
                                   PROFILE_CONTROL_LEVEL Level,
                                   unsigned int dwId);

Parametry

pszName

Název prvku profilování.Název je neplatný (metoda NameProfileA vrátí NAME_ERROR_INVALID_NAME), pokud:

Ukazatel předaný metodě NameProfileA má hodnotu NULL
Řetězec pszName začíná číslem
Řetězec pszName obsahuje mezeru
Řetězec pszName obsahuje některé z následujících znaků: , ; . ` ~ ! @ # $ % ^ & * ( ) = [ ] { } | \ ? / < >

Level

Označuje úroveň profilu, pro kterou lze použít sběru údajů o výkonu.Následující hodnoty PROFILE_CONTROL_LEVEL mohou být použity k označení jedné ze tří úrovní, na které lze sběr dat aplikovat:

Výčet	Popis
PROFILE_GLOBALLEVEL	Nastavení globální úrovně ovlivňuje všechny procesy a vlákna v profilovaném běhu.
PROFILE_PROCESSLEVEL	Nastavení úrovně procesu ovlivňuje všechna vlákna, která jsou součástí určeného procesu.
PROFILE_THREADLEVEL	Nastavení úrovně vláken ovlivňuje jen zadané vlákno.

dwId

Identifikátor úrovně profilování.Vyžaduje identifikátor procesu nebo vlákna, které je vygenerováno systémem.

Hodnota/Návratová hodnota vlastnosti

Funkce označuje úspěch nebo neúspěch pomocí výčtu PROFILE_COMMAND_STATUS.Návratová hodnota může být jedna z následujících:

Výčet	Popis
NAME_ERROR_ID_NOEXIST	Zadaný prvek profilování neexistuje.
NAME_ERROR_INVALID_NAME	Název je neplatný.
NAME_ERROR_LEVEL_NOEXIST	Zadaná úroveň profilování neexistuje.
NAME_ERROR_NO_SUPPORT	Zadaná operace není podporována.
NAME_ERROR_OUTOFMEMORY	Paměť nebyla pro záznam události dostupná.
NAME_ERROR_REDEFINITION	Název již byl přiřazen prvku profilování.Název v této funkci je ignorován.
NAME_ERROR_TEXTTRUNCATED	Text názvu přesáhl 32 znaků, včetně znaků Null, a byl zkrácen.
NAME_OK	Název byl úspěšně zaregistrován.

Poznámky

Každému procesu a vláknu může být přidělen pouze jeden název.Poté, co je prvek profilování pojmenován, jsou následná volání metody NameProfile ignorována.

Pokud je stejný název použit pro různá vlákna nebo procesy, bude záznam na této úrovni obsahovat všechny prvky s tímto názvem.

Pokud je zadán jiný než aktuální proces nebo vlákno, je potřeba se ujistit, že byl před pojmenováním inicializován a spuštěn.V opačném případě metoda NameProfile selže.

Důležité
Funkce CreateProcess() a CreateThread() aplikačního rozhraní mohou vrátit hodnotu před inicializací procesu nebo vlákna.

Ekvivalent v rozhraní .NET Framework

Microsoft.VisualStudio.Profiler.dll

Informace o funkci

Záhlaví	VSPerf.h
Knihovna	VSPerf.lib
Unicode	Implementováno jako: NameProfileW (Unicode) a NameProfileA (ANSI).

Příklad

Následující kód předvádí volání funkce NameProfile.V příkladu se předpokládá použití maker řetězců Win32 a nastavení kompilátoru pro ANSI, aby bylo dosaženo volání funkce povolené pro ANSI.

void ExerciseNameProfile()
{
    // Variables used to print output.
    HRESULT hResult;
    TCHAR tchBuffer[256];

    // Create and initialize variables to pass to 
    // ExerciseNameProfile.  The value of this 
    // parameter is based on the needs of the code;
    // and for the sake of simplicity in this example, 
    // the variable is assigned an arbitrary value.
    TCHAR * profileName = TEXT("ExerciseNameProfile");

    // Declare enumeration to hold result of call to 
    // ExerciseNameProfle.
    PROFILE_COMMAND_STATUS nameResult;

    nameResult =  NameProfile(
        profileName,
        PROFILE_GLOBALLEVEL,
        PROFILE_CURRENTID);

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

#ifdef DEBUG
    OutputDebugString(tchBuffer);
#endif
}

Viz také

Další zdroje

Visual Studio Profiler API Reference (nativní)

Sdílet prostřednictvím