LPTEXTOUTPROC

Artigo
10/10/2023

Quando o usuário executa uma operação de controle do código-fonte de dentro do ambiente de desenvolvimento integrado (IDE), o plug-in de controle do código-fonte pode querer transmitir mensagens de erro ou status relacionadas à operação. O plug-in pode exibir suas próprias caixas de mensagem para essa finalidade. No entanto, para uma integração mais perfeita, o plug-in pode passar cadeias de caracteres para o IDE, que as exibe em sua maneira nativa de exibir informações de status. O mecanismo para isso é o ponteiro de LPTEXTOUTPROC função. O IDE implementa essa função (descrita em mais detalhes abaixo) para exibir erro e status.

O IDE passa para o plug-in de controle do código-fonte um ponteiro de função para essa função, como parâmetro lpTextOutProc , ao chamar o SccOpenProject. Durante uma operação SCC, por exemplo, no meio de uma chamada para o SccGet envolvendo muitos arquivos, o plug-in pode chamar a LPTEXTOUTPROC função, passando periodicamente cadeias de caracteres para exibição. O IDE pode exibir essas cadeias de caracteres em uma barra de status, em uma janela de saída ou em uma caixa de mensagem separada, conforme apropriado. Opcionalmente, o IDE pode exibir determinadas mensagens com um botão Cancelar . Isso permite que o usuário cancele a operação e dá ao IDE a capacidade de passar essas informações de volta para o plug-in.

Signature

A função de saída do IDE tem a seguinte assinatura:

typedef LONG (*LPTEXTOUTPROC) (
   LPSTR display_string,
   LONG mesg_type
);

Parâmetros

display_string

Uma cadeia de texto a ser exibida. Essa cadeia de caracteres não deve ser terminada com um retorno de carro ou um feed de linha.

mesg_type

O tipo de mensagem. A tabela a seguir lista os valores com suporte para esse parâmetro.

Valor	Descrição
`SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR`	A mensagem é considerada Informação, Aviso ou Erro.
`SCC_MSG_STATUS`	A mensagem mostra o status e pode ser exibida na barra de status.
`SCC_MSG_DOCANCEL`	Enviado sem cadeia de caracteres de mensagem.
`SCC_MSG_STARTCANCEL`	Começa a exibir um botão Cancelar .
`SCC_MSG_STOPCANCEL`	Pára de exibir um botão Cancelar .
`SCC_MSG_BACKGROUND_IS_CANCELLED`	Pergunta ao IDE se a operação em segundo plano deve ser cancelada: o IDE retorna se a operação foi cancelada, caso contrário, retorna `SCC_MSG_RTN_CANCEL` `SCC_MSG_RTN_OK`. O `display_string` parâmetro é convertido como uma estrutura SccMsgDataIsCancelled , que é fornecida pelo plug-in de controle do código-fonte.
`SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE`	Informa ao IDE sobre um arquivo antes que ele seja recuperado do controle de versão. O `display_string` parâmetro é convertido como uma estrutura SccMsgDataOnBeforeGetFile , que é fornecida pelo plug-in de controle do código-fonte.
`SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE`	Informa ao IDE sobre um arquivo depois que ele foi recuperado do controle de versão. O `display_string` parâmetro é convertido como uma estrutura SccMsgDataOnAfterGetFile , que é fornecida pelo plug-in de controle do código-fonte.
`SCC_MSG_BACKGROUND_ON_MESSAGE`	Informa ao IDE o status atual de uma operação em segundo plano. O `display_string` parâmetro é convertido como uma estrutura SccMsgDataOnMessage , que é fornecida pelo plug-in de controle do código-fonte.

Valor retornado

Valor	Descrição
SCC_MSG_RTN_OK	A cadeia de caracteres foi exibida ou a operação foi concluída com êxito.
SCC_MSG_RTN_CANCEL	O usuário deseja cancelar a operação.

Exemplo

Suponha que o IDE chame o SccGet com vinte nomes de arquivo. O plug-in de controle do código-fonte deseja impedir o cancelamento da operação no meio de um recebimento de arquivo. Depois de obter cada arquivo, ele chama lpTextOutProc, passando-lhe as informações de status em cada arquivo, e envia uma SCC_MSG_DOCANCEL mensagem se ele não tem status para relatar. Se, a qualquer momento, o plug-in receber um valor de retorno do SCC_MSG_RTN_CANCEL IDE, ele cancelará a operação get imediatamente, para que nenhum outro arquivo seja recuperado.

Estruturas

SccMsgDataIsCancelled

typedef struct {
   DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;

Essa estrutura é enviada com a SCC_MSG_BACKGROUND_IS_CANCELLED mensagem. Ele é usado para comunicar a ID da operação em segundo plano que foi cancelada.

SccMsgDataOnBeforeGetFile

typedef struct {
   DWORD dwBackgroundOperationID;
   PCSTR szFile;
} SccMsgDataOnBeforeGetFile;

Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE mensagem. Ele é usado para comunicar o nome do arquivo prestes a ser recuperado e a ID da operação em segundo plano que está fazendo a recuperação.

SccMsgDataOnAfterGetFile

typedef struct {
   DWORD dwBackgroundOperationID;
   PCSTR szFile;
   SCCRTN sResult;
} SccMsgDataOnAfterGetFile;

Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE mensagem. Ele é usado para comunicar o resultado da recuperação do arquivo especificado, bem como a ID da operação em segundo plano que fez a recuperação. Consulte os valores de retorno para o SccGet para saber o que pode ser dado como resultado.

SccMsgDataOnMessage

typedef struct {
   DWORD dwBackgroundOperationID;
   PCSTR szMessage;
   BOOL bIsError;
} SccMsgDataOnMessage;

Essa estrutura é enviada com a SCC_MSG_BACKGROUND_ON_MESSAGE mensagem. Ele é usado para comunicar o status atual de uma operação em segundo plano. O status é expresso como uma cadeia de caracteres a ser exibida pelo IDE e bIsError indica a gravidade da mensagem (TRUE para uma mensagem de erro; FALSE para um aviso ou para uma mensagem informativa). O ID da operação em segundo plano que envia o status também é fornecido.

Exemplo de código

Aqui está um breve exemplo de chamada para enviar a mensagem, mostrando como transmitir a estrutura para a SCC_MSG_BACKGROUND_ON_MESSAGE chamadaLPTEXTOUTPROC.

LONG SendStatusMessage(
    LPTEXTOUTPROC pTextOutProc,
    DWORD         dwBackgroundID,
    LPCTSTR       pStatusMsg,
    BOOL          bIsError)
{
    SccMsgDataOnMessage msgData = { 0 };
    LONG                result  = 0;

    msgData.dwBackgroundOperationID = dwBackgroundID;
    msgData.szMessage               = pStatusMsg;
    msgData.bIsError                = bIsError;

    result = pTextOutProc(reinterpret_cast<LPCTSTR>(&msgData), SCC_MSG_BACKGROUND_ON_MESSAGE);
    return result;
}

Compartilhar via