NameProfile

Funkcja NameProfile przypisuje ciąg do określonego procesu lub wątku.

Interfejs API NameProfile jest dostępny tylko dla profilowania przy pomocy instrumentacji.Interfejs API NameProfile nie jest obsługiwany dla profilowania przy użyciu próbek.

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

Parametry

pszName

Nazwa elementu profilowania.Nazwa jest nieprawidłowa, (skutkująca, tym, że NameProfileA zwraca NAME_ERROR_INVALID_NAME), jeśli:

• Wskaźnik przekazany do NameProfileA ma wartość NULL

• Ciąg pszName zaczyna się od liczby

• Ciąg pszName zawiera spację

• Ciąg pszName zawiera dowolny z następujących znaków: ,;.`~!@#$%^&*()=[]{}|\?/<>

Level

Wskazuje poziom profilowania do którego ma być zastosowane zbieranie danych nt wydajności.Następujące wartości PROFILE_CONTROL_LEVEL mogą zostać użyte do wskazania jednego z trzech poziomów, do których ma być zastosowane zbieranie danych nt. wydajności.

Moduł wyliczający	Opis
PROFILE_GLOBALLEVEL	Ustawienie poziomu globalnego dotyczy wszystkich procesów i wątków w przebiegu profilowania.
PROFILE_PROCESSLEVEL	Ustawienie poziomu procesu dotyczy wszystkich wątków, które stanowią część określonego procesu.
PROFILE_THREADLEVEL	Ustawienie poziomu profilowania wątku dotyczy określonego wątku.

dwId

Identyfikator poziomu profilowania.Należy użyć identyfikatora procesu lub wątku, wygenerowanego przez system.

Wartość właściwości/Zwracana wartość

Funkcja określa sukces lub niepowodzenie przy użyciu wyliczenia PROFILE_COMMAND_STATUS.Zwracana wartość może być jedną z następujących:

Moduł wyliczający	Opis
NAME_ERROR_ID_NOEXIST	Określony element profilowania nie istnieje.
NAME_ERROR_INVALID_NAME	Nazwa jest nieprawidłowa.
NAME_ERROR_LEVEL_NOEXIST	Określony poziom profilowania nie istnieje.
NAME_ERROR_NO_SUPPORT	Określona operacja nie jest obsługiwana.
NAME_ERROR_OUTOFMEMORY	Brak dostepnej pamięci, aby zarejestrować zdarzenie.
NAME_ERROR_REDEFINITION	Nazwa została już przypisana do elementu profilowania.Nazwa w tej funkcji jest ignorowana.
NAME_ERROR_TEXTTRUNCATED	Tekst nazwy przekroczył 32 znaki, łącznie ze znakiem null i dlatego został obcięty.
NAME_OK	Nazwa została pomyślnie zarejestrowana.

Uwagi

Każdemu procesowi lub wątkowi można przypisać tylko jedną nazwę.Po nazwaniu elementu profilowania kolejne wywołania funkcji NameProfile dla tego elementu są ignorowane.

Jeśli ta sama nazwa jest podana dla różnych wątków lub procesów, raport będzie zawierał dane ze wszystkich elementów na tym poziomie z tą samą nazwą.

Jeśli określisz proces lub wątek inny niż bieżący, należy upewnić się, że został zainicjowany i zaczął działać przed nadaniem mu nazwy.W przeciwnym wypadku metoda NameProfile nie zadziała.

Ważne
Funkcje CreateProcess() i CreateThread() interfejsu API mogą zwrócić wartość zanim wątek lub proces zostanie zainicjowany.

Odpowiednik w programie .NET Framework

Microsoft.VisualStudio.Profiler.dll

Informacje o funkcji

Nagłówek	Załącz VSPerf.h
Biblioteka	Użyj VSPerf.lib
Unikod	Zaimplementowane jako NameProfileW (Unicode) i NameProfileA (ANSI).

Przykład

Poniższy kod ilustruje wywołanie funkcji NameProfile.W przykładzie założono użycie makr ciągów Win32 i ustawień kompilatora ANSI aby ustalić, czy kod wywołuje włączoną funkcję 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
}

Zobacz też

Inne zasoby

Interfejsy API profilera Visual Studio (Native)