LPTEXTOUTPROC

Artykuł
10/10/2023

Gdy użytkownik wykonuje operację kontroli źródła z poziomu zintegrowanego środowiska projektowego (IDE), wtyczka kontroli źródła może chcieć przekazać komunikaty o błędach lub stanie związane z operacją. Wtyczka może wyświetlać własne pola komunikatów w tym celu. Jednak w celu zapewnienia bardziej bezproblemowej integracji wtyczka może przekazywać ciągi do środowiska IDE, które następnie wyświetla je w natywny sposób wyświetlania informacji o stanie. Mechanizmem tego jest LPTEXTOUTPROC wskaźnik funkcji. Środowisko IDE implementuje tę funkcję (opisaną bardziej szczegółowo poniżej) na potrzeby wyświetlania błędu i stanu.

Środowisko IDE przekazuje do wtyczki kontroli źródła wskaźnik funkcji do tej funkcji, jako lpTextOutProc parametr, podczas wywoływania SccOpenProject. Podczas operacji SCC, na przykład w środku wywołania do SccGet obejmującego wiele plików, wtyczka może wywołać LPTEXTOUTPROC funkcję, okresowo przekazując ciągi do wyświetlenia. Środowisko IDE może wyświetlać te ciągi na pasku stanu, w oknie danych wyjściowych lub w osobnym oknie komunikatu, odpowiednio. Opcjonalnie środowisko IDE może mieć możliwość wyświetlania niektórych komunikatów za pomocą przycisku Anuluj . Dzięki temu użytkownik może anulować operację, a środowisko IDE może przekazać te informacje z powrotem do wtyczki.

Podpis

Funkcja wyjściowa środowiska IDE ma następujący podpis:

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

Parametry

display_string

Ciąg tekstowy do wyświetlenia. Ten ciąg nie powinien być przerywany zwrotem karetki ani kanałem informacyjnym.

mesg_type

Typ komunikatu. W poniższej tabeli wymieniono obsługiwane wartości dla tego parametru.

Wartość	Opis
`SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR`	Komunikat jest uznawany za informacje, ostrzeżenie lub błąd.
`SCC_MSG_STATUS`	Komunikat zawiera stan i może być wyświetlany na pasku stanu.
`SCC_MSG_DOCANCEL`	Wysłane bez ciągu komunikatu.
`SCC_MSG_STARTCANCEL`	Rozpoczyna wyświetlanie przycisku Anuluj .
`SCC_MSG_STOPCANCEL`	Zatrzymuje wyświetlanie przycisku Anuluj .
`SCC_MSG_BACKGROUND_IS_CANCELLED`	Pyta ide, czy operacja w tle ma zostać anulowana: środowisko IDE zwraca `SCC_MSG_RTN_CANCEL` informację, czy operacja została anulowana; w przeciwnym razie zwraca wartość `SCC_MSG_RTN_OK`. Parametr `display_string` jest rzutowany jako struktura SccMsgDataIsCancelled , która jest dostarczana przez wtyczkę kontroli źródła.
`SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE`	Informuje środowisko IDE o pliku przed pobraniem go z kontroli wersji. Parametr `display_string` jest rzutowany jako struktura SccMsgDataOnBeforeGetFile , która jest dostarczana przez wtyczkę kontroli źródła.
`SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE`	Informuje środowisko IDE o pliku po pobraniu go z kontroli wersji. Parametr `display_string` jest rzutowany jako struktura SccMsgDataOnAfterGetFile , która jest dostarczana przez wtyczkę kontroli źródła.
`SCC_MSG_BACKGROUND_ON_MESSAGE`	Informuje środowisko IDE o bieżącym stanie operacji w tle. Parametr `display_string` jest rzutowany jako struktura SccMsgDataOnMessage, która jest dostarczana przez wtyczkę kontroli źródła.

Wartość zwracana

Wartość	Opis
SCC_MSG_RTN_OK	Ciąg został wyświetlony lub operacja została ukończona pomyślnie.
SCC_MSG_RTN_CANCEL	Użytkownik chce anulować operację.

Przykład

Załóżmy, że środowisko IDE wywołuje moduł SccGet z dwudziestu nazwami plików. Wtyczka kontroli źródła chce zapobiec anulowaniu operacji w trakcie pobierania pliku. Po otrzymaniu każdego pliku wywołuje lpTextOutProcmetodę , przekazując informacje o stanie dla każdego pliku i wysyła SCC_MSG_DOCANCEL komunikat, jeśli nie ma stanu do raportowania. Jeśli w dowolnym momencie wtyczka odbiera wartość SCC_MSG_RTN_CANCEL zwracaną ze środowiska IDE, natychmiast anuluje operację pobierania, aby nie pobrać więcej plików.

Struktury

SccMsgDataIsCancelled

typedef struct {
   DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;

Ta struktura jest wysyłana z komunikatem SCC_MSG_BACKGROUND_IS_CANCELLED . Służy do przekazywania identyfikatora operacji w tle, która została anulowana.

SccMsgDataOnBeforeGetFile

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

Ta struktura jest wysyłana z komunikatem SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE . Służy do przekazywania nazwy pliku, który ma zostać pobrany, oraz identyfikator operacji w tle, która wykonuje pobieranie.

SccMsgDataOnAfterGetFile

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

Ta struktura jest wysyłana z komunikatem SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE . Służy do przekazywania wyniku pobierania określonego pliku, a także identyfikatora operacji w tle, która wykonała pobieranie. Zobacz wartości zwracane dla obiektu SccGet , aby zobaczyć, co można podać w wyniku.

SccMsgDataOnMessage

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

Ta struktura jest wysyłana z komunikatem SCC_MSG_BACKGROUND_ON_MESSAGE . Służy do przekazywania bieżącego stanu operacji w tle. Stan jest wyrażony jako ciąg wyświetlany przez środowisko IDE i bIsError wskazuje ważność komunikatu (TRUE w przypadku komunikatu o błędzie; FALSE ostrzeżenie lub komunikat informacyjny). Podano również identyfikator operacji w tle wysyłającej stan.

Przykład kodu

Oto krótki przykład wywołania w LPTEXTOUTPROC celu wysłania komunikatu SCC_MSG_BACKGROUND_ON_MESSAGE , pokazujący, jak rzutować strukturę wywołania.

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

Share via