< PreviousField Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 59 of 145 Table 61 – FinishExportFile Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitExportFile service. After the call of this service the FileHandle becomes invalid and shall not be used anymore. DoSave Boolean Defines whether the file export should be finalized and the file is stored on disk by the FDI Client or the export should be aborted Response 5.2.2.19 InitImportFile Service 5.2.2.19.1 Description This service is used by the UIP to load a file with access rights of the FDI Client. A file dialog is opened by the FDI Client to select path and filename. The selected path and filename as well as a handle are returned. The handle shall be used in the ReadImportFile and FinishImportFile to transfer the content of the file to the UIP and finish or cancel the operation. 5.2.2.19.2 Parameters Table 62 defines the parameters for the service. Table 62 – InitImportFile Service parameters Name Type Description Request SuggestedFileName String The name of the file to be loaded. Can be changed by the user. The SuggestedFileName is not fully qualified, and the host manages the default directory where the file should be loaded. The user can change the name and path. This is returned as FullyQualifiedFileName. Filter String Filter contains a list of possible file extensions and file types. The user can select one of the options during export. The selected filter is returned in SelectedFilterIndex. For each file extension and file type, the filter string contains a description, followed by the vertical bar (|) and the filter pattern. The strings for different filtering options are separated by the vertical bar. For example: “Word document (*.docx)|*.docx| PDF (*.pdf)|*.pdf” SuggestedFilterIndex Integer Index into the filter that is selected as default value. Response FullyQualifiedFileName String Fully qualified file name where the file was loaded from. SelectedFilterIndex Integer The selected filter. FileHandle <technology dependent> Handle that is used in WriteExportFile and FinishExportFile to identify the overall operation. 5.2.2.20 ReadImportFile Service 5.2.2.20.1 Description This service is used to transfer data from the file to be imported. UIPs typically need to call this service several times to get the full content of the file. 5.2.2.20.2 Parameters Table 60 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 60 of 145 Table 63 – ReadImportFile Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitExportFile service. MaxLength Integer Defines the length in bytes that should be returned in Data. If the end of file is reached all data until the end of the file is returned. The FDI Client is allowed to return less data than specified length. Only positive values are allowed. Response Data Byte[] Contains the returned data of the file. If the Byte array is empty it indicates that the end of the file is reached. 5.2.2.21 FinishImportFile Service 5.2.2.21.1 Description This service finalizes the import file operation. UIPs can call this service before the end of the file is reached to cancel the import operation. 5.2.2.21.2 Parameters Table 60 defines the parameters for the service. Table 64 – FinishImportFile Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitImportFile service. After the call of this service the FileHandle becomes invalid and shall not be used anymore. Response 5.2.2.22 InitOpenDefaultApplication Service 5.2.2.22.1 Description This service is used by the UIP to advice the FDI Client to open a file with its registered default application (e.g. PDF, Excel). The FDI Client may restrict which applications are allowed to use. The operation is split into three services. First, the UIP needs to call InitOpenDefaultApplication, then it needs to call WriteOpenDefaultApplication potentially several times to transfer the data of the file to the FDI Client and finally FinishOpenDefaultApplication to either cancel the operation or indicate the complete file has been transferred and the FDI Client shall open the default application for it. How the FDI Client manages the file is host specific, for example in a temporary folder. UIPs shall not expect that the transferred file is stored persistently by the FDI Client. 5.2.2.22.2 Parameters Table 77 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 61 of 145 Table 65 – InitOpenDefaultApplication Service parameters Name Type Description Request SuggestedFileName String The name of the file to be saved. Can be changed by the FDI Client. The SuggestedFileName is not fully qualified, and the FDI Client is responsible to manage the file. Response FileHandle <technology dependent> Handle that is used in WriteOpenDefaultApplication and FinishOpenDefaultApplication to identify the overall operation. 5.2.2.23 WriteOpenDefaultApplication Service 5.2.2.23.1 Description This service is used to transfer data to the file to be opened by the default applications. UIPs will typically call this service several times to provide the full content of the file. 5.2.2.23.2 Parameters Table 77 defines the parameters for the service. Table 66 – WriteOpenDefaultApplication Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitOpenDefaultApplication service. Data Byte[] An array of bytes containing data to be written to the file. The file created with InitOpenDefaultApplication is empty and the first WriteOpenDefaultApplication call for the file starts filling the file from the beginning, all additional calls add the data to the end of the file. Writing an empty array of Bytes returns a Good result code without any effect on the file. Response 5.2.2.24 FinishOpenDefaultApplication Service 5.2.2.24.1 Description This service finalizes the open default application operation. It either cancels or finalizes the operation when the content of the file to be opened is fully written using the WriteOpenDefaultApplication service. 5.2.2.24.2 Parameters Table 77 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 62 of 145 Table 67 – FinishOpenDefaultApplication Service parameters Name Type Description Request FileHandle <technology dependent> Handle of the file returned in the InitOpenDefaultApplicaton service. After the call of this service the FileHandle becomes invalid and shall not be used anymore. DoOpen Boolean Defines whether the default application shall be opened by the FDI Client or the operation should be aborted. Response 5.2.2.25 GetHostingProperties Service 5.2.2.25.1 Description This service is used by the UIP to get hosting environment properties as a list of key/value pairs. The content of this list shall be constant during lifecycle of the UIP. For a mandatory property its key shall exist at any time. A non-mandatory property might be missing completely (no key at all). For any existing key there is always a valid value that shall be able to be used as defined in the description. 5.2.2.25.2 Parameters Table 79 defines the parameters for the service. Table 68 – GetHostingProperties Service parameters Name Type Description Request Response PropertyList <technology dependent> A list of pairs of strings (key, value) 5.2.2.25.3 Key Value Pairs Table 80 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 63 of 145 Table 69 – GetHostingProperties Key Value Pairs Key Value Mandatory Description LocalClientDataPath <Fully qualified folder path> Yes The FDI Client provides a fully qualified path to a folder where the UIP has the permission to directly: • open files from • save files to • add subfolders to • delete subfolders from The folder shall be persistent and shall be accessible by the UIP. All UIPs shall get the same LocalClientDataPath from the FDI Client, allowing different UIPs or different UIP instances to share data. UIP developers need to be aware of this. A file might be blocked by means of the operating system because it is opened by another UIP and other UIPs might create, manipulate, or delete files and folders under the LocalClientDataPath. It is recommended to create a subfolder for a UIP and manage all UIP data in this subfolder. Host installations might choose a network folder shared by all FDI Clients to manage the persistent data. However, the LocalClientDataPath might also be a local folder of the FDI Client. Therefore, the stored data might only be accessible on a specific FDI Client and different for another FDI Client of the same FDI host. It is recommended to store device specific data in the information model of the device, where it is synchronized between FDI Clients. User settings shall be managed with the LoadUserSettings and SaveUserSettings services and not in the file system in order to provide the same settings between different FDI Clients of the same FDI host. Context {Online, Offline} Yes Defines the context (online or offline) from which the UIP is invoked. currentCountry <technology dependent> Yes Information describing the current country that shall be considered by the UIP for internal globalization purposes. The data type of the value is technology dependent. currentCulture <technology dependent> Yes Information describing the current culture that shall be considered by the UIP for internal localization purposes. The data type of the value is technology dependent. Parameter Type Definitions 5.2.3.1 DefaultResult Definition The components of this parameter are defined in Table 70. Table 70 – DefaultResult definition Name Type Description DefaultResult Integer Definition of a button on a message box. Used to specify the default button and the button selected by the user. This value is an enumeration with one of the following values: BUTTONNONE_0 BUTTONOK_1 BUTTONCANCEL_2 BUTTONYES_3 BUTTONNO_4 5.2.3.2 ButtonSet The components of this parameter are defined in Table 71. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 64 of 145 Table 71 – ButtonSet definition Name Type Description ButtonSet Integer Definition of the buttons on a message box or progress bar shown to the user. This value is an enumeration with one of the following values: BUTTONSETOK_0 Only ok button is shown BUTTONSETOKCANCEL_1 Ok and cancel buttons are shown BUTTONSETYESNOCANCEL_2 Yes, no, and cancel buttons are shown BUTTONSETYESNO_3 Yes and no buttons are shown 5.2.3.3 AcknStyle The components of this parameter are defined in Table 72. Table 72 – AcknStyle definition Name Type Description AcknStyle Integer The style of the message box or progress bar shown to the user. For example, this parameter may influence the icon of the message box. This value is an enumeration with one of the following values: ACKNSTYLEINFO_0 Information style ACKNSTYLEWARNING_1 Warning style ACKNSTYLERROR_2 Error style 6 UIP 6.1 UIP Services Services 6.1.1.1 Activate Service 6.1.1.1.1 Description This service is used by the FDI Client to initialize a UIP (see 6.1.2). The FDI Client shall call this service after the creation of an instance of a UIP. The following rules define the window type: • A modal window is used, if the UIP style = dialog, or the invoking parent (UID or UIP) is modal. • A non-modal window is used if the UIP style = window and the invoking parent runs in non-modal mode also. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 65 of 145 6.1.1.1.2 Parameters Table 73 defines the parameters for the service. Table 73 – Activate Service parameters Name Type Description Request hostingInterface Interface FDI Client hosting interface to be used by the UIP (see 5.2). deviceAccessInterface Interface FDI Client device access interface to be used by the UIP (see 5.1). context UInteger Specifies in which context the UIP is activated: 0_ONLINE 1_OFFLINE The Client shall derive the context from the FunctionalGroup where this UIP has been retrieved from; i.e., whether the FunctionalGroup is part of the Offline device representation or the online device representation. If a UIP is invoked from another UIP with the OpenUserInterface service, the context is inherited. localeSetting <technology dependent> The locale description consists of at least a language identifier and country. The format of the property value is technology dependent. Response The localeSetting shall not depend on the operating system settings. The operating system settings can be used by default but shall be alterable by the user. The language identifier shall indicate the language for localized textual information. Parameter country shall be used to apply country-specific regulations such as allowed engineering units. To do this, the UIP will modify the EngineeringUnit Attribute of correlated Variable Nodes to match the specified country. The FDI Server is then responsible to reformat the values accordingly. 6.1.1.2 Deactivate Service 6.1.1.2.1 Description This service is used by the FDI Client to deactivate a UIP. The UIP shall release all references to other components and finish all pending or running functions including UIPs that it opened that are still open. The UIP may indicate that it is not ready to be deactivated. This shall be used if cancelling pending or running functions would have severe side-effects. 6.1.1.2.2 Parameters Table 74 defines the parameters for the service. Table 74 – Deactivate Service parameters Name Type Description Request Response deactivateCancelled Boolean Indication whether the UIP refused the Deactivate request. deactivateCancelled = “true”denotes that the UIP refused the Deactivate request. deactivateCancelled = “false”denotes that the UIP accepted the Deactivate request. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 66 of 145 6.1.1.3 SetSystemLabel Service 6.1.1.3.1 Description This service is used by the FDI Client to specify a human identifier of the UIP instance in the context of the FDI Client. The label shall be used for user interface elements displayed and managed by the UIP (e.g. a message box) and will assure that the user can uniquely identify to which Device the user interface element is directed. The UIP can extend this label with specific information when appropriate. The FDI Client shall call this service before the Activate service (see 6.1.1.1). If it has not been called, the UIP shall use the text portion of the Label Attribute of the Device by default (see 5.1.3.2) 6.1.1.3.2 Parameters Table 75 defines the parameters for the service. Table 75 – SetSystemLabel Service parameters Name Type Description Request systemLabel String Human readable label that identifies the UIP within the FDI Client. Response None. 6.1.1.4 SetTraceLevel Service 6.1.1.4.1 Description This service is used by the FDI Client to notify the UIP of the types of Trace messages that should be logged via the Trace service (see 5.2.2.8). Multiple types can be set (for instance: Critical, Error, and Warning). 6.1.1.4.2 Parameters Table 76 defines the parameters for the service. Table 76 – SetTraceLevel Service parameters Name Type Description Request traceLevel TraceLevel Trace level that shall control the type of information (see Table 81). Response 6.1.1.5 GetStandardUIActionItems Service 6.1.1.5.1 Description This service is used by the FDI Client to get the available standard UI actions in the UIP (for instance: Close, Apply, Help). The FDI Client provides consistent representation of these standard UI actions, in the FDI Client UI area. 6.1.1.5.2 Parameters Table 77 defines the parameters for the service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2 , Ed. 1.2.0, 27 Jun 2019 Page 67 of 145 Table 77 – GetStandardUIActionItems Service parameters Name Type Description Request Response StandardUIActionItems[] StandardUIActionItem List of Standard Actions provided by the UIP. 6.1.1.6 GetSpecificUIActionItems Service 6.1.1.6.1 Description This service is used by the FDI Client to get the available UI actions that are specific for the UIP. The FDI Client provides consistent representation of these UI actions, in the FDI Client UI area. 6.1.1.6.2 Parameters Table 78 defines the parameters for the service. Table 78 – GetSpecificUIActionItems Service parameters Name Type Description Request Response SpecificUIActionItems[] SpecificUIActionItem List of UI actions specific for the UIP. 6.1.1.7 InvokeStandardUIAction Service 6.1.1.7.1 Description This service is used by the FDI Client to notify the UIP to perform a standard action (for instance: Close, Apply, Help). The FDI Client passes the type of standard action to be performed in this service. 6.1.1.7.2 Parameters Table 79 defines the parameters for the service. Table 79 – InvokeStandardUIAction Service parameters Name Type Description Request actionId StandardUIAction One of the values defined in 6.1.2.2. Response 6.1.1.8 InvokeSpecificUIAction Service 6.1.1.8.1 Description This service is used by the FDI Client to notify the UIP to perform a UI action that is specific to this UIP. The FDI Client passes the identifier of the action to be performed in this service. Field Device Integration (FDI) – Part 2: Client RELEASED FCG TS62769-2, Ed. 1.2.0, 27 Jun 2019 Page 68 of 145 6.1.1.8.2 Parameters Table 80 defines the parameters for the service. Table 80 – InvokeSpecificUIAction Service parameters Name Type Description Request actionId UInteger This is the identifier of the specific UI action to be performed. Response Parameter type definitions 6.1.2.1 TraceLevel TraceLevel is defined in Table 81. Table 81 – TraceLevel definition Name Type Description TraceLevel UInteger Severity level that controls the type of information that is passed to the Trace service (see 5.2.2.8). This value is a bit enumeration with one of the following values: NONE_0 Completely switch off tracing CRITICAL_1 Fatal error or application crash ERROR_2 Recoverable error WARNING_4 Noncritical error INFO_8 Informational message VERBOSE_16 Debugging trace 6.1.2.2 StandardUIAction Standard actions are defined to allow consistency in appearance and processing. They will be requested by the hosting Client. These actions are not expected to be mapped 1:1 to user interface buttons. Rather, the Client will display OK, CANCEL, and APPLY. Clicking OK, CANCEL or APPLY by the User causes the following actions to be called. • OK will cause a call to the Apply action followed by a call to the Close action. • APPLY will cause a call to the Apply action. • CANCEL will cause a call to the Close action. If changes are still outstanding, the UIP shall open a dialog asking the user to confirm. The StandardUIAction enumeration is defined in Table 82. Next >