LPTEXTOUTPROC

项目
10/10/2023

当用户从集成开发环境（IDE）内执行源代码管理操作时，源代码管理插件可能想要传达与操作相关的错误或状态消息。插件可以为此显示自己的消息框。但是，为了进行更无缝的集成，插件可以将字符串传递给 IDE，然后以本机方式显示状态信息。此机制是 LPTEXTOUTPROC 函数指针。 IDE 实现此函数（下面更详细地介绍）以显示错误和状态。

调用 SccOpenProject 时，IDE 会将函数指针作为参数传递给源代码管理插件，作为lpTextOutProc参数。例如，在 SCC 操作期间，在调用涉及多个文件的 SccGet 的过程中，插件可以调用LPTEXTOUTPROC函数，定期传递要显示的字符串。 IDE 可能会根据需要在状态栏、输出窗口或单独的消息框中显示这些字符串。（可选）IDE 可以使用“取消”按钮显示某些消息。这使用户能够取消操作，并使 IDE 能够将此信息传递回插件。

Signature

IDE 的输出函数具有以下签名：

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

参数

display_string

要显示的文本字符串。不应使用回车符或换行符终止此字符串。

mesg_type

消息的类型。下表列出了此参数支持的值。

值	说明
`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 结构，该结构由源代码管理插件提供。

返回值

值	说明
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 发送。它用于传达已取消的后台操作的 ID。

SccMsgDataOnBeforeGetFile

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

此结构随消息一起 SCC_MSG_BACKGROUND_ON_BEFORE_GET_FILE 发送。它用于传达要检索的文件的名称以及正在检索的后台操作的 ID。

SccMsgDataOnAfterGetFile

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

此结构随消息一起 SCC_MSG_BACKGROUND_ON_AFTER_GET_FILE 发送。它用于传达检索指定文件的结果以及执行检索的后台操作的 ID。有关结果可以给出的内容，请参阅 SccGet 的返回值。

SccMsgDataOnMessage

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

此结构随消息一起 SCC_MSG_BACKGROUND_ON_MESSAGE 发送。它用于传达后台操作的当前状态。状态表示为 IDE 要显示的字符串，并 bIsError 指示消息的严重性（TRUE 错误消息; FALSE 警告或信息性消息）。还会提供发送状态的后台操作的 ID。

代码示例

下面是调用以发送SCC_MSG_BACKGROUND_ON_MESSAGE消息的LPTEXTOUTPROC简短示例，演示如何为呼叫转换结构。

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

通过