LPTEXTOUTPROC

Lorsque l’utilisateur exécute une opération de contrôle de code source à partir de l’environnement de développement intégré (IDE), le plug-in de contrôle de code source peut souhaiter transmettre des messages d’erreur ou d’état relatifs à l’opération. Le plug-in peut afficher ses propres boîtes de message à cet effet. Toutefois, pour une intégration plus transparente, le plug-in peut passer des chaînes à l’IDE, qui les affiche ensuite de manière native pour afficher les informations d’état. Le mécanisme pour cela est le LPTEXTOUTPROC pointeur de fonction. L’IDE implémente cette fonction (décrite plus en détail ci-dessous) pour afficher l’erreur et l’état.

L’IDE passe au plug-in de contrôle de code source un pointeur de fonction vers cette fonction, en tant que lpTextOutProc paramètre, lors de l’appel de SccOpenProject. Pendant une opération SCC, par exemple, au milieu d’un appel à SccGet impliquant de nombreux fichiers, le plug-in peut appeler la LPTEXTOUTPROC fonction, en passant régulièrement des chaînes à afficher. L’IDE peut afficher ces chaînes dans une barre d’état, dans une fenêtre de sortie ou dans une zone de message distincte, le cas échéant. Si vous le souhaitez, l’IDE peut être en mesure d’afficher certains messages avec un bouton Annuler . Cela permet à l’utilisateur d’annuler l’opération et lui donne la possibilité de transmettre ces informations au plug-in.

Signature

La fonction de sortie de l’IDE a la signature suivante :

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

Paramètres

display_string

Chaîne de texte à afficher. Cette chaîne ne doit pas être arrêtée avec un retour chariot ou un flux de ligne.

mesg_type

Type de message. Le tableau suivant répertorie les valeurs prises en charge pour ce paramètre.

Valeur	Description
SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR	Le message est considéré comme Des informations, un avertissement ou une erreur.
SCC_MSG_STATUS	Le message affiche l’état et peut être affiché dans la barre d’état.
SCC_MSG_DOCANCEL	Envoyé sans chaîne de message.
SCC_MSG_STARTCANCEL	Commence à afficher un bouton Annuler .
SCC_MSG_STOPCANCEL	Arrête d’afficher un bouton Annuler .
SCC_MSG_BACKGROUND_IS_CANCELLED	Demande à l’IDE si l’opération en arrière-plan doit être annulée : l’IDE retourne SCC_MSG_RTN_CANCEL si l’opération a été annulée ; sinon, retourne SCC_MSG_RTN_OK. Le display_string paramètre est casté en tant que structure SccMsgDataIsCancelled , fournie par le plug-in de contrôle de code source.
SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE	Indique à l’IDE qu’un fichier est récupéré à partir du contrôle de version. Le display_string paramètre est casté en tant que structure SccMsgDataOnBeforeGetFile , fournie par le plug-in de contrôle de code source.
SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE	Indique à l’IDE qu’un fichier a été récupéré à partir du contrôle de version. Le display_string paramètre est casté en tant que structure SccMsgDataOnAfterGetFile , fournie par le plug-in de contrôle de code source.
SCC_MSG_BACKGROUND_ON_MESSAGE	Indique à l’IDE l’état actuel d’une opération en arrière-plan. Le display_string paramètre est casté en tant que structure SccMsgDataOnMessage , fournie par le plug-in de contrôle de code source.

Valeur retournée

Valeur	Description
SCC_MSG_RTN_OK	La chaîne a été affichée ou l’opération a été effectuée avec succès.
SCC_MSG_RTN_CANCEL	L’utilisateur souhaite annuler l’opération.

Exemple

Supposons que l’IDE appelle SccGet avec vingt noms de fichiers. Le plug-in de contrôle de code source souhaite empêcher l’annulation de l’opération au milieu d’une obtention de fichier. Après avoir obtenu chaque fichier, il appelle lpTextOutProc, en lui transmettant les informations d’état sur chaque fichier et envoie un SCC_MSG_DOCANCEL message s’il n’a pas d’état à signaler. Si, à tout moment, le plug-in reçoit une valeur de retour de SCC_MSG_RTN_CANCEL l’IDE, il annule immédiatement l’opération d’obtention, afin qu’aucun autre fichier ne soit récupéré.

Structures

SccMsgDataIsCancelled

typedef struct {
   DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;

Cette structure est envoyée avec le SCC_MSG_BACKGROUND_IS_CANCELLED message. Il est utilisé pour communiquer l’ID de l’opération en arrière-plan qui a été annulée.

SccMsgDataOnBeforeGetFile

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

Cette structure est envoyée avec le SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE message. Il est utilisé pour communiquer le nom du fichier sur le point d’être récupéré et l’ID de l’opération en arrière-plan qui effectue la récupération.

SccMsgDataOnAfterGetFile

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

Cette structure est envoyée avec le SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE message. Il est utilisé pour communiquer le résultat de la récupération du fichier spécifié ainsi que l’ID de l’opération d’arrière-plan qui a effectué la récupération. Consultez les valeurs de retour du SccGet pour ce qui peut être donné en conséquence.

SccMsgDataOnMessage

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

Cette structure est envoyée avec le SCC_MSG_BACKGROUND_ON_MESSAGE message. Il est utilisé pour communiquer l’état actuel d’une opération en arrière-plan. L’état est exprimé sous la forme d’une chaîne à afficher par l’IDE et bIsError indique la gravité du message (TRUE pour un message d’erreur ; FALSE pour un avertissement ou pour un message d’information). L’ID de l’opération en arrière-plan envoyant l’état est également donné.

Exemple de code

Voici un bref exemple d’appel LPTEXTOUTPROC pour envoyer le SCC_MSG_BACKGROUND_ON_MESSAGE message, montrant comment convertir la structure de l’appel.

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

Voir aussi

• Fonctions de rappel implémentées par l’IDE
• Plug-ins de contrôle de code source