工业软件接入ISCDesk

前提条件

在gitee中将SDK开源源码下载至本地，代码仓地址为https://gitee.com/HuaweiCloudDeveloper/huaweicloud-dme-iscdesk-cpp/tree/master-dev/。

当前提供两种方式获取SDK开源源码（注意：请选择“master-dev”分支代码）：

• 将“huaweicloud-DME-ISCDesk-cpp”代码仓克隆至本地。
• 将“huaweicloud-DME-ISCDesk-cpp”代码压缩包下载至本地。

操作步骤

1. 在您编译应用程序的电脑上使用Visual Studio打开SDK源码工程。
2. 根据您的项目的编译器/工具集版本以及Windows SDK版本编译SDK工程。
3. 将“IscdeskSdk\SdkApi\include”文件夹复制到您的项目中。
4. 根据系统版本，将“IscdeskSdk\SdkApi\bin\x64\Release”或者“IscdeskSdk\SdkApi\bin\win32\Release”中的“.dll”文件复制到您的项目库文件夹中。
   

   如果工业软件同时拥有x86和x86_64版本，您需要将win32和x64中的“.dll”文件复制到相应的库文件夹中。

5. 添加“SdkInvoker.h”和“IscdeskSdkIdl.h”头文件。
   在应用代码工程中，复制如下代码段：

   #include "SdkInvoker.h所在相对路径"
   #include "IscdeskSdkIdl.h所在相对路径"

   

   “SdkInvoker.h”所在路径：SDK包解压后，“SdkInvoker.h”文件所在的指定目录的相对路径。例如：“ISCDesk-PC-SDK\Sdk\Include\interface\SdkInvoker.h”。

   “IscdeskSdkIdl.h”所在路径：SDK包解压后，“IscdeskSdkIdl.h”文件所在的指定目录的相对路径。例如：“ISCDesk-PC-SDK\Sdk\Include\sdk\IscdeskSdkIdl.h”。

6. 调用对应API来设置SDK。
   1. 加载“IscdeskApi.dll”或者“IscdeskApi64.dll”文件。

      // 使用时需要包含如下头文件
      #include "IscdeskApi\Sdk\Include\interface\SdkInvoker.h" 
      #include "IscdeskApi\Sdk\Include\sdk\IscdeskSdkIdl.h"
      HMODULE sdkHandle = LoadLibraryA("IscdeskApi.dll所在相对路径");
      if (sdkHandle == NULL) {
          // 加载失败需要退出
      }

      

      “IscdeskApi.dll”所在路径：SDK源码编译后，“IscdeskApi.dll”文件所在的指定目录的相对路径。例如，“IscdeskSdk\SdkApi\bin\Win32\Release\IscdeskApi.dll”。

   2. 调用“IscdeskSdkCheckingEnvironment”接口，检查ISCDesk客户端是否启动。

      // 使用IscdeskSdk.h
      SDK::SdkInvoker invoker(SdkHandle);
      ResultStatus ret = invoker.IscdeskSdkCheckingEnvironment();
      if (ret != STATUS_SUCCESS) { 
          // 检查失败需要退出
      }

   3. 初始化SDK。

      ResultStatus ret = invoker.IscdeskFactory()->Init()
      if (ret != ResultStatus::STATUS_SUCCESS) {
          // 初始化失败需要退出
      }

7. 根据SDK的接口功能，开发所需的SDK功能模块，功能模块详情请参见改造功能模块说明。
   

   工业软件调用SDK函数时，入参必须使用UTF-8编码格式。SDK产生回调事件时，通知工业软件的消息也为UTF-8编码格式。若存在编码格式冲突，请工业软件做好编码格式转换，避免因为编码格式不同导致的问题。

   1. 基础SDK接口功能。此处为Demo示例，请您根据实际情况在应用代码工程中进行开发。

      Example example; 
        /* Sdk初始化 */
        ResultStatus resutStatus_1 = invoker.IscdeskFactory()->Init(); 
        /* 将用户工业软件类的事件接收函数注册到Sdk中 */
        invoker.IscdeskFactory()->RegisterEventRecall(&example, &Example::EventRecall);
        ResultStatus resultStatus_2 = invoker.IscdeskFactory()->ShutOut();

   2. 管理在云SDK接口功能。此处为Demo示例，请您根据实际情况在应用代码工程中进行开发。

       /* 用户工业软件调用试用到期通知并获取license函数接口（如果有试用期） */
      ResultStatus resultStatus_3 = invoker->TrialExpirationAndGetLicense(LicenseType::LICENSE_TYPE_FILE,
           "devInfo", "license.lic");
      /* 用户工业软件调用获取License文件请求函数接口 */
        ResultStatus resultStatus_4 = invoker->GetLicenseFileRequest(fileName, devInfo);
       /* 用户工业软件调用获取License字符串请求函数接口 */
        ResultStatus resultStatus_5 = invoker->GetLicenseStringRequest(devInfo); 
        /* 用户工业软件调用License验证结果通知接口 */
        ResultStatus resultStatus_6 = invoker.IscdeskFactory()->invoker->LicenseVerifyNotify(verifyResult, errorMsg);
        /* 用户工业软件调用升级信息查询接口 */
        ResultStatus resultStatus_7 = invoker.IscdeskFactory()->invoker->CheckNewVersions();
        /* 用户工业软件调用升级通知接口 */
        ResultStatus resultStatus_8 = invoker.IscdeskFactory()->invoker->UpgradeNotify(bUpgrade);

   3. 数据在云SDK接口功能。此处为Demo示例，请您根据实际情况在应用代码工程中进行开发。

      /* 用户工业软件调用打开云端文件接口 */  
        ResultStatus resultStatus_9 = invoker.IscdeskFactory()->OpenCloudFile(filePath);    
      /* 用户工业软件调用另存普通文件至云端文件接口 */
        ResultStatus resultStatus_10 = invoker.IscdeskFactory()->SelectSaveAsPath(filePath);  
      /* 用户工业软件调用另存装配体文件至云端文件接口 */
        ResultStatus resultStatus_11 = invoker.IscdeskFactory()->SelectSaveAsPath(filePath, true);  
      /* 用户工业软件调用保存普通文件至云端文件接口 */
        ResultStatus resultStatus_12 = invoker.IscdeskFactory()->Save(saveFilePath);
      /* 用户工业软件调用保存装配体文件至云端文件接口 */
        ResultStatus resultStatus_13 = invoker.IscdeskFactory()->Save(saveFilePath, true);

   4. （可选）计算在云SDK接口功能。此处以Demo示例，请根据实际情况在您的应用代码工程中进行开发。

        ResultStatus resultStatus_14 = invoker.IscdeskFactory()->GetSolution(filePath);

   

   SDK回调事件产生说明：

   • “EVENT_OPENCLOUDFILE_RESULT”：打开云端文件事件。工业软件调用“OpenCloudFile”打开云端文件接口并选择云端文件后，SDK产生此事件。此事件触发时，SDK会将云端文件路径信息连同事件一起告知工业软件，工业软件可根据此事件进行打开文件操作。
   • “EVENT_SAVE_RESULT”：保存结果回复事件。工业软件调用“Save”保存至云端接口、“SelectSaveAsPath”另存为云端接口后产生此事件。此事件触发时，SDK会将保存文件结果连同事件一起告知工业软件。
   • “EVENT_UPDATE”：升级事件。工业软件调用“CheckNewVersions”接口后，通知ISCDesk检查版本信息，查看是否存在升级版本。如果存在升级信息，则SDK产生升级事件。升级事件触发时，SDK会将升级事件告知工业软件，工业软件可自行决定是否退出升级或继续使用。
   • “EVENT_UPGRADENOTICE”：升级信息通知事件。工业软件调用“CheckNewVersions”接口后，通知ISCDesk检查版本信息，查看是否存在升级版本。ISCDesk查询版本信息后通知SDK，SDK产生升级信息通知事件。SDK将升级信息通知事件连同升级信息一起告知工业软件。
   • “EVENT_CLIENT_EXIT”：ISCDesk客户端关闭事件。工业软件与ISCDesk客户端正常连接时，ISCDesk客户端关闭后，SDK会产生客户端关闭事件。客户端关闭事件触发时，SDK会将客户端关闭事件告知工业软件，工业软件根据此事件可自行决定是否退出、是否降级处理或其他自定义操作。
   • “EVENT_LICENSE_VERIFY”：License验证事件。工业软件调用“GetLicenseFileRequest ”或“GetLicenseStringRequest”接口后需要等待，直到SDK产生此事件。此事件触发时SDK会将License路径信息或License字符串信息连同事件一起告知工业软件，工业软件可根据此事件进行License验证操作。

     SDK告知工业软件的信息字符串中包含：“LicenseFilePath”字段（License路径），“LicenseContent”字段（License字符串内容），“LicenseType”字段（License类型，包含License文件和License字符串两种类型。），以及“Status”字段（License获取状态）。

     当License文件验证时：“LicenseType”字段值为“file”，“LicenseFilePath”字段为License文件路径，“LicenseContent”字段不存在；当License字符串验证时：“LicenseType”字段值为“string”，“LicenseContent”字段为License字符串内容，“LicenseFilePath”字段不存在。当License请求获取成功时，“Status”字段为“success”；失败时为“failed”；取消获取License时为“cancel”。

   • EVENT_SHORTCUT_SAVETOCLOUD：保存云端文件的快捷键事件。用户在ISCDesk上设置并启用保存云端文件快捷键后，当用户在工业软件窗口输入对应快捷键后，SDK产生保存云端文件的快捷键事件，并通知工业软件，工业软件可根据此事件进行保存云端文件操作。
   • EVENT_SHORTCUT_SAVEASTOCLOUD：另存为云端文件的快捷键事件。用户在ISCDesk上设置并启用另存为云端文件快捷键后，当用户在工业软件窗口输入对应快捷键后，SDK产生另存为云端文件的快捷键事件，并通知工业软件，工业软件可根据此事件进行另存为云端文件操作。
   • EVENT_UPLOAD_START：文件上传云端开始事件。当工业软件进行保存云端文件或另存为云端文件操作后，文件上传云端开始时，SDK产生文件上传云端开始事件并通知工业软件，建议工业软件在收到此事件后，对上传中的文件禁止保存，避免在上传过程中由于文件修改导致与预期上传结果不一致。
   • EVENT_UPLOAD_END：文件上传云端结束事件。当工业软件进行保存云端文件或另存为云端文件操作后，文件上传云端结束时，SDK产生文件上传云端结束事件并通知工业软件，建议工业软件在收到此事件后，对上传中的文件解除禁止保存。
   • “EVENT_UNKONW”：未知事件。

   注：“RegisterEventRecall”函数注册的回调函数为事件接收函数，事件接收函数获得的参数仅为事件类型及不同事件对应的信息，具体业务逻辑需要工业软件自行添加。且事件接收函数中禁止调用ShutOut函数，否则会造成死锁。

8. 检查函数返回的错误码。如果为失败状态，则请检查调用方式或运行环境等是否有问题。
   

   错误码说明：

   • STATUS_SUCCESS：成功
   • STATUS_FAILURE：普通错误
   • ERROR_CLIENT_OFFLINE：ISCDesk客户端未登录
   • ERROR_CLIENT_NOINSTALL：ISCDesk客户端未安装
   • ERROR_INTERFACE_INVALID：接口不可用
   • ERROR_SHM_READ_FAILED：共享内存读取失败
   • ERROR_NETWORK_INITIALIZE_FAILED：网络初始化失败
   • ERROR_NETWORK_ERROR：网络不可用
   • ERROR_NETWORK_UNREACHBLE：网络不可达
   • ERROR_LICENSE_EXPIRE：软件许可过期
   • ERROR_LICENSE_NOEXIST：软件许可不存在
   • ERROR_UNKNOWN：未知错误

9. 当您关闭客户端工业软件应用时，需要释放SDK。

     // 当不需要IscdeskSdk时，您需要结束IscdeskSdk
     ResultStatus resultStatus = invoker.IscdeskFactory()->ShutOut();
     invoker.DestoryIscdesk();
     // 释放该SDK库
     FreeLibrary(handle);