NameProfile

Artigo
08/08/2011

O NameProfile função atribui uma seqüência de caracteres especificado do processo ou thread.

A API NameProfile só está disponível para a criação de perfil de instrumentação. A API NameProfile não há suporte para a criação de perfil de amostragem.

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

Parâmetros

pszName

O nome do elemento de criação de perfil. Um nome é inválido (resultando em NAME_ERROR_INVALID_NAME de retorno de NameProfileA) se:

O ponteiro passado para NameProfileA é um valor nulo
Os dados de seqüência de pszName começam com um número.
Os dados de seqüência de pszName contém um espaço
Os dados de seqüência de pszName contém os seguintes caracteres:,.' ~! @ #$ % ^ & * () = [] {} | \? / < >

Level

Indica o nível de perfil ao qual o desempenho pode ser aplicada a coleta de dados. O seguinte PROFILE_CONTROL_LEVEL valores podem ser usados para indicar um dos três níveis de coleta de dados para que o desempenho pode ser aplicada:

Enumerador	Descrição
PROFILE_GLOBALLEVEL	Configuração de nível global afeta todos os processos e threads em que a criação de perfil executar.
PROFILE_PROCESSLEVEL	Configuração de nível de processo afeta todos os segmentos que fazem parte do processo especificado.
PROFILE_THREADLEVEL	Definindo o perfil de configuração do nível de thread afeta o segmento especificado.

dwId

Identificador de nível de criação de perfil. Use o processo ou thread identificador gerado pelo sistema.

Valor de Propriedade/Valor Retornado

A função indica sucesso ou fracasso usando PROFILE_COMMAND_STATUS enumeração. O valor de retorno pode ser um destes procedimentos:

Enumerador	Descrição
NAME_ERROR_ID_NOEXIST	O elemento de criação de perfil especificado não existe.
NAME_ERROR_INVALID_NAME	O nome é inválido.
NAME_ERROR_LEVEL_NOEXIST	O perfil especificado não existe.
NAME_ERROR_NO_SUPPORT	Não há suporte para a operação especificada.
NAME_ERROR_OUTOFMEMORY	Não havia memória disponível para registrar o evento.
NAME_ERROR_REDEFINITION	Um nome já foi atribuído ao elemento de perfil. O nome nesta função é ignorado.
NAME_ERROR_TEXTTRUNCATED	O texto de nome excedido de 32 caracteres, incluindo o caractere nulo e, portanto, foi truncado.
NAME_OK	Nome foi registrado com êxito.

Comentários

Apenas um nome pode ser atribuído a cada processo ou segmento. Depois de um elemento de criação de perfil é nomeado, as chamadas subseqüentes para NameProfile desse elemento são ignoradas.

Se o mesmo nome for fornecido para diferentes segmentos ou processos, o relatório incluirá dados de todos os elementos nesse nível com esse nome.

Se você especificar um processo ou segmento diferente da atual, você deve Certifique-se de que ele foi inicializado e iniciado em execução antes de nomeá-la. Caso contrário, o método NameProfile falhará.

Importante
As funções de CreateProcess () e CreateThread() API podem retornar antes do thread ou processo é inicializado.

Equivalente do NET Framework

Microsoft.VisualStudio.Profiler.dll

Informações de função

Header	Incluir VSPerf.h
Biblioteca	Usar VSPerf.lib
Unicode	Implementada como NameProfileW (Unicode) e NameProfileA (ANSI).

Exemplo

O código a seguir ilustra a chamada de função NameProfile. O exemplo supõe que o uso de macros de seqüência de caracteres de Win32 e as configurações do compilador ANSI determinar se o código chama o ANSI habilitado a função.

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
}

Consulte também

Outros recursos

Profiler Referência API do Visual Studio (nativos)

Compartilhar via