NameProfile

Article
08/21/2008

Mise à jour : novembre 2007

La fonction NameProfile assigne une chaîne au processus ou au thread spécifié.

L'API NameProfile est uniquement disponible pour le profilage d'instrumentation. L'API NameProfile n'est pas prise en charge pour le profilage d'échantillonnage.

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

Paramètres

pszName

Nom de l'élément de profilage. Un nom n'est pas valide (provoquant le retour par NameProfileA de NAME_ERROR_INVALID_NAME) si :

Le pointeur passé dans NameProfileA est une valeur NULL
Les données de type chaîne de pszName commencent par un nombre
Les données de type chaîne de pszName contiennent un espace
Les données de type chaîne de pszName contiennent chacun des caractères suivants : ;. '~! @ #$% ^ & * () = [] {} | \?/< >

Level

Indique le niveau de profil auquel la collecte de données de performance peut être appliquée. Les énumérateurs PROFILE_CONTROL_LEVEL suivants permettent d'indiquer l'un des trois niveaux auxquels la collecte de données de performance peut être appliquée :

dwId

Identificateur du niveau de profilage. Utilisez l'identificateur de processus ou de thread généré par le système.

Valeur de propriété/valeur de retour

La fonction indique la réussite ou l'échec en utilisant l'énumération PROFILE_COMMAND_STATUS. La valeur de retour peut être l'une des suivantes :

Énumérateur	Description
NAME_ERROR_ID_NOEXIST	L'élément de profilage spécifié n'existe pas.
NAME_ERROR_INVALID_NAME	Le nom n'est pas valide.
NAME_ERROR_LEVEL_NOEXIST	Le niveau de profil spécifié n'existe pas.
NAME_ERROR_NO_SUPPORT	L'opération spécifiée n'est pas prise en charge.
NAME_ERROR_OUTOFMEMORY	La mémoire n'était pas disponible pour enregistrer l'événement.
NAME_ERROR_REDEFINITION	Un nom a déjà été assigné à l'élément de profil. Le nom dans cette fonction est ignoré.
NAME_ERROR_TEXTTRUNCATED	Le texte du nom a dépassé 32 caractères y compris le caractère Null et a été donc tronqué.
NAME_OK	Le nom a été enregistré avec succès.

Notes

Un seul nom peut être assigné à chaque processus ou thread. Une fois qu'un élément de profilage est nommé, les appels suivants à NameProfile pour cet élément sont ignorés.

Si le même nom est attribué à des threads ou processus différents, le rapport inclura les données de tous les éléments à ce niveau avec ce nom.

Si vous spécifiez un processus ou un thread différent de l'actuel, vous devez vérifier qu'il a été initialisé et qu'il a commencé à s'exécuter avant de le nommer. Sinon, la méthode NameProfile échoue.

Remarque importante :
Les fonctions d'API CreateProcess() et CreateThread() peuvent être retournées avant que le thread ou le processus ne soit initialisé.

Équivalent .NET Framework

Microsoft.VisualStudio.Profiler.dll

Informations sur la fonction

En-tête	Inclure VSPerf.h
Bibliothèque	Utiliser VSPerf.lib
Unicode	Implémenté en tant que NameProfileW (Unicode) et NameProfileA (ANSI).

Exemple

Le code suivant illustre l'appel de la fonction NameProfile. L'exemple suppose l'utilisation des macros de chaîne Win32 et des paramètres du compilateur pour ANSI afin de déterminer si le code appelle la fonction compatible 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
}

Voir aussi

Autres ressources

Référence des API du générateur de profils Visual Studio (Native)

Partager via