NameProfile

La función NameProfile asigna una cadena al proceso o subproceso especificado.

La API de NameProfile sólo está disponible para la generación de perfiles de instrumentación.La API NameProfile no se admite para la generación de perfiles de muestreo.

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

Parámetros

pszName

Nombre del elemento de generación de perfiles.Un nombre no es válido (lo que hace que NameProfileA devuelva NAME_ERROR_INVALID_NAME) si:

El puntero que se ha pasado en NameProfileA es un valor NULL
Los datos de cadena de pszName comienzan con un número
Los datos de cadena de pszName contienen un espacio
Los datos de cadena de pszName contienen alguno de los caracteres siguientes: ,;.`~!@#$%^&*()=[]{}|\?/<>

Level

Indica el nivel de perfil al que se puede aplicar la recolección de datos de rendimiento.Los valores PROFILE_CONTROL_LEVEL siguientes se pueden utilizar para indicar uno de los tres niveles a los que se puede aplicar la recolección de datos de rendimiento:

Enumerator	Descripción
PROFILE_GLOBALLEVEL	La configuración de nivel global afecta a todos los procesos y subprocesos de la ejecución de generación de perfiles.
PROFILE_PROCESSLEVEL	La configuración de nivel de proceso afecta a todos los subprocesos que forman parte del proceso especificado.
PROFILE_THREADLEVEL	La configuración de nivel de subprocesos de la generación de perfiles afecta al subproceso especificado.

dwId

Identificador del nivel de generación de perfiles.Se debe utilizar el identificador del proceso o del subproceso generado por el sistema.

Valor de propiedad y valor devuelto

La función indica si la operación es correcta o errónea mediante la enumeración PROFILE_COMMAND_STATUS.El valor devuelto puede ser cualquiera de los siguientes:

Enumerator	Descripción
NAME_ERROR_ID_NOEXIST	El elemento de generación de perfiles especificado no existe.
NAME_ERROR_INVALID_NAME	El nombre no es válido.
NAME_ERROR_LEVEL_NOEXIST	El nivel de perfil especificado no existe.
NAME_ERROR_NO_SUPPORT	No se admite la operación especificada.
NAME_ERROR_OUTOFMEMORY	La memoria no estaba disponible para registrar el evento.
NAME_ERROR_REDEFINITION	Ya se asignó un nombre al elemento de perfil.Se omite el nombre que figura en esta función.
NAME_ERROR_TEXTTRUNCATED	El texto del nombre superó 32 caracteres incluido el carácter null y, por consiguiente, se truncó.
NAME_OK	El nombre se registró correctamente.

Comentarios

Sólo se puede asignar un nombre a cada proceso o subproceso.Una vez asignado el nombre a un elemento de generación de perfiles, se omiten las llamadas subsiguientes a NameProfile para ese elemento.

Si se asigna el mismo nombre a subprocesos o procesos diferentes, el informe incluirá los datos de todos los elementos del nivel que tengan ese nombre.

Si especifica un proceso o subproceso distinto del actual, debe asegurarse de que se ha inicializado y que ha comenzado a ejecutarse antes de asignarle el nombre.De lo contrario, se producirá un error en el método NameProfile.

Importante
Las funciones API CreateProcess() y CreateThread() pueden devolver valores antes de que se inicialice el subproceso o proceso.

Equivalente en .NET Framework

Microsoft.VisualStudio.Profiler.dll

Información de la función

Encabezado	Incluir VSPerf.h
Biblioteca	Utilizar VSPerf.lib
Unicode	Se implementa como NameProfileW (Unicode) y NameProfileA (ANSI).

Ejemplo

El código siguiente muestra la llamada a la función NameProfile.En el ejemplo se asume que se utilizan macros de cadenas de Win32 y la configuración del compilador de ANSI para determinar si el código llama a la función habilitada para 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
}

Vea también

Otros recursos

Referencia a la API del generador de perfiles de Visual Studio (Nativa)

Last updated on 2013-02-19