LPTEXTOUTPROC

Artículo
10/10/2023

Cuando el usuario ejecuta una operación de control de código fuente desde dentro del entorno de desarrollo integrado (IDE), es posible que el complemento de control de código fuente quiera transmitir mensajes de error o estado relacionados con la operación. El complemento puede mostrar sus propios cuadros de mensaje para este propósito. Sin embargo, para una integración más fluida, el complemento puede pasar cadenas al IDE, que después los muestra de forma nativa para mostrar información de estado. El mecanismo para esto es el puntero de LPTEXTOUTPROC función. El IDE implementa esta función (que se describe con más detalle a continuación) para mostrar el error y el estado.

El IDE pasa al complemento de control de código fuente un puntero de función a esta función, como parámetro lpTextOutProc , al llamar a SccOpenProject. Durante una operación SCC, por ejemplo, en medio de una llamada a SccGet que implica muchos archivos, el complemento puede llamar a la LPTEXTOUTPROC función, pasando periódicamente cadenas para mostrar. El IDE puede mostrar estas cadenas en una barra de estado, en una ventana de salida o en un cuadro de mensaje independiente, según corresponda. Opcionalmente, el IDE puede mostrar determinados mensajes con un botón Cancelar . Esto permite al usuario cancelar la operación y ofrece al IDE la capacidad de volver a pasar esta información al complemento.

Signature

La función de salida del IDE tiene la siguiente firma:

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

Parámetros

display_string

Cadena de texto que se va a mostrar. Esta cadena no debe terminarse con un retorno de carro o una fuente de línea.

mesg_type

El tipo de mensaje. En la tabla siguiente se enumeran los valores admitidos para este parámetro.

Value	Descripción
`SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR`	El mensaje se considera Información, Advertencia o Error.
`SCC_MSG_STATUS`	El mensaje muestra el estado y se puede mostrar en la barra de estado.
`SCC_MSG_DOCANCEL`	Enviado sin cadena de mensaje.
`SCC_MSG_STARTCANCEL`	Comienza a mostrar un botón Cancelar .
`SCC_MSG_STOPCANCEL`	Deja de mostrar un botón Cancelar .
`SCC_MSG_BACKGROUND_IS_CANCELLED`	Pregunta al IDE si se va a cancelar la operación en segundo plano: EL IDE devuelve `SCC_MSG_RTN_CANCEL` si se canceló la operación; de lo contrario, devuelve `SCC_MSG_RTN_OK`. El `display_string` parámetro se convierte como una estructura SccMsgDataIsCancelled , que proporciona el complemento de control de código fuente.
`SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE`	Indica al IDE sobre un archivo antes de recuperarlo del control de versiones. El `display_string` parámetro se convierte como una estructura SccMsgDataOnBeforeGetFile , que proporciona el complemento de control de código fuente.
`SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE`	Indica al IDE sobre un archivo después de recuperarlo del control de versiones. El `display_string` parámetro se convierte como una estructura SccMsgDataOnAfterGetFile , que proporciona el complemento de control de código fuente.
`SCC_MSG_BACKGROUND_ON_MESSAGE`	Indica al IDE el estado actual de una operación en segundo plano. El `display_string` parámetro se convierte como una estructura SccMsgDataOnMessage , que proporciona el complemento de control de código fuente.

Valor devuelto

Value	Descripción
SCC_MSG_RTN_OK	La cadena se mostró o la operación se completó correctamente.
SCC_MSG_RTN_CANCEL	El usuario quiere cancelar la operación.

Ejemplo

Supongamos que el IDE llama a SccGet con veinte nombres de archivo. El complemento de control de código fuente quiere impedir la cancelación de la operación en medio de una obtención de archivos. Después de obtener cada archivo, llama a lpTextOutProc, y le pasa la información de estado en cada archivo y envía un SCC_MSG_DOCANCEL mensaje si no tiene ningún estado para informar. Si en cualquier momento el complemento recibe un valor devuelto del SCC_MSG_RTN_CANCEL IDE, cancela la operación get inmediatamente, de modo que no se recuperen más archivos.

Estructuras

SccMsgDataIsCancelled

typedef struct {
   DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;

Esta estructura se envía con el SCC_MSG_BACKGROUND_IS_CANCELLED mensaje . Se usa para comunicar el identificador de la operación en segundo plano que se canceló.

SccMsgDataOnBeforeGetFile

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

Esta estructura se envía con el SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE mensaje . Se usa para comunicar el nombre del archivo a punto de recuperarse y el identificador de la operación en segundo plano que está realizando la recuperación.

SccMsgDataOnAfterGetFile

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

Esta estructura se envía con el SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE mensaje . Se usa para comunicar el resultado de recuperar el archivo especificado, así como el identificador de la operación en segundo plano que realizó la recuperación. Vea los valores devueltos de SccGet para obtener lo que se puede dar como resultado.

SccMsgDataOnMessage

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

Esta estructura se envía con el SCC_MSG_BACKGROUND_ON_MESSAGE mensaje . Se usa para comunicar el estado actual de una operación en segundo plano. El estado se expresa como una cadena que va a mostrar el IDE e bIsError indica la gravedad del mensaje (TRUE para un mensaje de error; FALSE para una advertencia o para un mensaje informativo). También se proporciona el identificador de la operación en segundo plano que envía el estado.

Ejemplo de código

Este es un breve ejemplo de llamada LPTEXTOUTPROC para enviar el SCC_MSG_BACKGROUND_ON_MESSAGE mensaje, en el que se muestra cómo convertir la estructura de la llamada.

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;
}

Compartir a través de