Project Provider Framework

From LabVIEW Wiki
Jump to: navigation, search

The Project Provider Framework is an unsupported API used to extend LabVIEW in various ways, mostly relating to the project interface. While NI does not provide official support for Project Providers, nor guarantee their stability in future versions, they have provided some documentation as well as a community forum for the framework; this was originally only available to NI-approved developers but has since been opened to the general public.

Features

Things that can be done using Project Providers:

  1. Add Menu Items (globally or per specific item types)
  2. Add Toolbar Buttons
  3. Add Items to the Project Tree
  4. Add Right-Click (Popup or Context) Menu Items
  5. Customize the Double-Click Behavior of an Item
  6. Modify the Name or Icon of an Item in the Project Tree
  7. Save More Information Related to an Item
  8. Drag and Drop Items to and Within a Project

Primary vs Secondary Providers

Providers can be either a Primary or a Secondary Provider.

  • A Primary Provider puts one or more new item types into the project tree.
  • A Secondary Provider adds additional functionality to existing items, but is not responsible for creating or managing those items.

Therefore, a Secondary Provider does not cause new items to be displayed in the tree but attaches to items shown by other Primary Providers.

Project Provider INI File

A Project Provider is defined by an INI file located in the [LabVIEW 20xx]\resource\Framework\Providers\GProviders directory in the LabVIEW installation directory. This file contains paths to "interface VI's", which determine the locations of other VI's that implement the plugin's functionality. 

[Provider]
SupportedType={D60740D6-F254-4BBC-5675-8858F35B810E}
GlobalItemInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Global_Interface.vi
ItemInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Item_Interface.vi
ProviderInterfaceVI=..\SecondaryProviderExample1\SecondaryProviderExample1_Provider_Interface.vi
IsPrimary=0
LicenseName=None
InterfaceVersion=1.0
Signature=J7W9927AAAAAA5TBNTSSTTLWR29CNT9X

The INI files can contain the following keys:

Keys Description
SupportedInterface Indicates which interfaces are supported by the provider.
SupportedType Specifies a GUID that represents the type of project item type. (See ProjectItems)

Must be formatted as follows: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} For a Secondary Provider, this can point to the Alias of the item type it wants to attach to instead of the GUID.

Alias Is a unique string that like the GUID, is used to identify the project item type (applies to Primary Providers only).
IsPrimary
  • 1 – Primary provider (defines a new item type in the project).
  • 0 – Secondary provider (adds functionality to the existing item(s) in the project).
ItemInterfaceVI Defines the VI that enumerates the “Item” interface.
ProviderInterfaceVI Defines the VI that enumerates the “Provider” interface.
GlobalItemInterfaceVI Defines the VI that enumerates the ”Global” item interface.
CreateNewWizardInterfaceVI Defines the VI that enumerates the “CreateNewWizard” interface.
SourceControlInterfaceVI Defines the VI that enumerates the “SourceControl” interface.
DeployInterfaceVI Defines the VI that enumerates the “Deploy” interface.
BuildInterfaceVI Defines the VI that enumerates the “Build” interface.
CreateNewWizardHost (Primary providers only) Defines which “New” menu to add to e.g., Source, Build.
InterfaceVersion Specifies the interface version used by the provider. Currently, this must be set to 1.0.
Signature Digital signature – generated by NI. (Or See Below)

Supported Types

The SupportedType key in a Primary Provider’s INI file acts as the type ID of the item it creates. If it is a new type this GUID must be in the form of: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

The SupportedType key in a Secondary Provider’s INI file defines which item type is supported (or Alias in the case of Primary Providers).

See ProjectItems for the list of LabVIEW Item Types.

Supported Interfaces

Primary Providers specify their supported interfaces by including them in their INI file. Secondary Providers specify their supported interfaces through:

  1. Implicitly inheriting the Interfaces through the Primary Provider they support as defined by the SupportedType key
  2. Explicitly defining the Interfaces through the regular keys in the INI file just as the Primary Provider does

Signature

For LabVIEW to load a project provider, its INI file must contain a valid "signature" consisting of an enciphered MD5 hash of certain other values in the INI file, generated using a signing tool provided by NI. This is an artifact from before the framework was officially made public, though the method of generating the signature had been reverse-engineered and was publicly known before that point.

Algorithm

What follows is an explanation of how the "signature" is determined. If you are using the official signing tool (or an unofficial one) you do not need to know this, but it might be useful for tool developers or anyone curious.

First, take the values (not the keys) in the INI file in order, and concatenate them. Only include the values for keys in this list (rule of thumb: string values, not Boolean or numeric values, and don't include the Signature key of course):

  • "InterfaceVersion"
  • "LicenseRestrictions"
  • "LicenseVersion"
  • "LicenseName"
  • "Alias"
  • "SupportedType"
  • "SupportedInterface"
  • "CreateNewWizardHost"
  • "BuildInterfaceVI"
  • "DeployInterfaceVI"
  • "SourceControlInterfaceVI"
  • "CreateNewWizardInterfaceVI"
  • "GlobalItemInterfaceVI"
  • "ProviderInterfaceVI"
  • "ItemInterfaceVI"

Do not include spaces or other delimiters between values in the concatenated string. Take the MD5 hash of this string, and apply the following substitution cipher to each of the digits: 

Change: 0123456789ABCDEF
    To: T3C5K7W9SBNRJLX2

Finally, for each pair of two consecutive digits, switch them. For example, CRTTR3X7 would become RCTT3R7X.

Interface VIs

The framework specifies a list of interfaces that providers must implement. Each interface VI is a list of paths to dispatch VIs that point to each of the required methods that the providers must implement. Only the methods that the provider will provide need to be implemented. The VIs implementing these methods must conform to the particular Connector Pane but the contents can be completely customized. Once a provider-based event occurs the provider framework will run the appropriate VI if a method has been customized for that event in the provider. For example if Item.OnSelect has been implemented, it will be called when the project item is selected. The Interface VIs:

  1. Build - Defines events that apply to builds, i.e. items under Build Specifications, in the project tree.
  2. CreateNewWizard - Defines events that occur while adding items of new types to the project tree.
  3. Global - Defines global-level events not tied to a specific item type.
  4. Item - Defines events that occur to individual items in the project tree.
  5. ProjectDeployItem - Defines events that support deploying of an item in the project tree.
  6. Provider - Defines events that occur to multiple items in the project tree.
  7. SourceControl - Defines events that apply to source code control functionality.

Directory Structure

All the VI- based providers and provider APIs can be found at [LabVIEW 20xx]\resource\framework\Providers\. This directory further contains the following directories:

  1. API - This directory contains type-definition controls defining the specifications for the various interface VIs. It also contains several helpful VIs that can be used from within the provider framework to perform frequent provider tasks, e.g., getting or setting project item properties.
  2. Common - This directory also contains reusable VIs that are useful to writing providers. They are simple VIs and unlike the API VIs do not call into the provider framework.
  3. GProviders - This directory was introduced in LabVIEW 2011. It is mandatory to have all the INI files in this directory for LabVIEW versions post-2010 for the providers to be loaded. This change is backward-compatible: a provider with its INI in the GProviders directory behaves the same way in a previous version of LabVIEW. It is highly recommended to follow this standard while building providers with any version of LabVIEW.
  4. Icons - This is the recommended location for all your provider icons. You can place icons at other locations as well but remember to specify the path with respect to the INI file location when setting the icons in provider VIs.
  5. <Provider> - Each provider should be located in a separate directory under [LabVIEW 20xx]\resource\Frameworks\Provider. This is not strictly enforced but is highly recommended.

Working directory

The working directory for a provider is where its INI file is located. All relative paths to interface VIs in the INI should be specified with respect to this location.

GProviders is the working directory for all providers in LabVIEW 2011. This should be kept in mind while specifying relative paths into API/Common VIs, e.g., the icon file path should be relative to the GProviders directory and not the VI in which the provider is setting the icon.

API VIs

The API and the Common directories provide several reusable VIs that come handy while building providers, for example, VIs that set the icon of an item in the project tree, set the menu or the toolbar options. The VIs in the API directory call into the provider framework to implement their functionality. A descriptive list of these VIs can be found API VIs.

Documentation and Examples

See also

Retrieved from "https://labviewwiki.org/w/index.php?title=Project_Provider_Framework&oldid=32434"