LPTEXTOUTPROC

發行項
01/13/2024

當使用者從集成開發環境（IDE）內執行原始檔控制作業時，原始檔控制外掛程式可能會想要傳達與作業相關的錯誤或狀態消息。外掛程式可以針對此目的顯示自己的消息框。不過，為了進行更順暢的整合，外掛程式可以將字串傳遞至 IDE，然後以原生方式顯示它們來顯示狀態資訊。此機制是函 LPTEXTOUTPROC 式指標。 IDE 會實作此函式（如下所述）來顯示錯誤和狀態。

當呼叫 SccOpenProject 時，lpTextOutProcIDE 會將函式指標傳遞至此函式的函式指標作為參數。例如，在 SCC 作業期間，在涉及許多檔案的 SccGet 呼叫中間，外掛程式可以呼叫 LPTEXTOUTPROC 函式，定期傳遞要顯示的字串。 IDE 可能會視情況在狀態列、輸出視窗或個別消息框中顯示這些字串。或者，IDE 可以使用 [取消] 按鈕來顯示特定訊息。這可讓使用者取消作業，並讓 IDE 能夠將此資訊傳回外掛程式。

簽章

IDE 的輸出函式具有下列簽章：

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

參數

display_string

要顯示的文字字串。此字串不應以歸位字元或換行字元終止。

mesg_type

訊息的類型。下表列出此參數支援的值。

值	Description
`SCC_MSG_INFO, SCC_MSG_WARNING, SCC_MSG_ERROR`	訊息會被視為資訊、警告或錯誤。
`SCC_MSG_STATUS`	訊息會顯示狀態，而且可以顯示在狀態列中。
`SCC_MSG_DOCANCEL`	未傳送任何訊息字串。
`SCC_MSG_STARTCANCEL`	開始顯示 [取消] 按鈕。
`SCC_MSG_STOPCANCEL`	停止顯示 [取消] 按鈕。
`SCC_MSG_BACKGROUND_IS_CANCELLED`	詢問 IDE 是否要取消背景作業：如果取消作業，IDE 會 `SCC_MSG_RTN_CANCEL` 傳回 ;否則會傳 `SCC_MSG_RTN_OK`回。參數 `display_string` 會轉換成 SccMsgDataIsCancelled 結構，其由原始檔控制外掛程式提供。
`SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE`	在從版本控制擷取檔案之前，告知 IDE。參數 `display_string` 會轉換成 SccMsgDataOnBeforeGetFile 結構，其由原始檔控制外掛程式提供。
`SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE`	在從版本控制擷取檔案之後，告知 IDE。參數 `display_string` 會轉換成由原始檔控制外掛程式提供的 SccMsgDataOnAfterGetFile 結構。
`SCC_MSG_BACKGROUND_ON_MESSAGE`	告知 IDE 背景作業的目前狀態。參數 `display_string` 會轉換成 SccMsgDataOnMessage 結構，其由原始檔控制外掛程式提供。

傳回值

值	Description
SCC_MSG_RTN_OK	字串已顯示，或作業順利完成。
SCC_MSG_RTN_CANCEL	使用者想要取消作業。

範例

假設 IDE 會呼叫具有 20 個檔名的 SccGet 。原始檔控制外掛程式想要防止在檔案取得中間取消作業。取得每個檔案之後，它會呼叫 lpTextOutProc、傳遞每個檔案的狀態資訊，並在沒有要報告的狀態時傳送 SCC_MSG_DOCANCEL 訊息。如果外掛程式隨時收到來自 IDE 的 SCC_MSG_RTN_CANCEL 傳回值，它會立即取消取得作業，這樣就不會再擷取任何檔案。

結構

SccMsgDataIsCancelled

typedef struct {
   DWORD dwBackgroundOperationID;
} SccMsgDataIsCancelled;

此結構會隨訊息一起 SCC_MSG_BACKGROUND_IS_CANCELLED 傳送。它用來傳達已取消之背景作業的標識碼。

SccMsgDataOnBeforeGetFile

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

此結構會隨訊息一起 SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE 傳送。它用來傳達即將擷取的檔名，以及執行擷取之背景作業的標識碼。

SccMsgDataOnAfterGetFile

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

此結構會隨訊息一起 SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE 傳送。它用來傳達擷取指定檔案的結果，以及執行擷取之背景作業的標識碼。如需結果可以提供的內容，請參閱 SccGet 的傳回值。

SccMsgDataOnMessage

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

此結構會隨訊息一起 SCC_MSG_BACKGROUND_ON_MESSAGE 傳送。它用來傳達背景作業的目前狀態。狀態會以 IDE 所顯示的字串表示，並 bIsError 指出訊息的嚴重性（TRUE 針對錯誤訊息; FALSE 針對警告或參考訊息）。也會提供傳送狀態的背景作業標識碼。

程式碼範例

以下是呼叫 LPTEXTOUTPROC 以傳送 SCC_MSG_BACKGROUND_ON_MESSAGE 訊息的簡短範例，示範如何轉換呼叫的結構。

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

共用方式為