Customize the C++ registry values

The sample plug-includes two registry files: SAMDBG.REG, a windows-readable registry file for use during development and SAMPRLS.REG, a registry file for distribution on the iSeries™ server.

The following table describes the sections in these registry files, and recommends changes for use when developing your own plug-in.

Primary registry key

; -------------------------------------------------
; Define the primary registry key for the plugin
; NOTE: NLS and ServerEntryPoint DLL names must 
; not contain qualified directory paths
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample]
"Type"="PLUGIN"
"NLS"="sampmri.dll"
"NameID"=dword:00000080
"DescriptionID"=dword:00000081
"MinimumIMPIRelease"="NONE"
"MinimumRISCRelease"="030701"
"ProductID"="NONE"
"ServerEntryPoint"="sampext.dll"

See the topic Example Primary registry key for a description of each of the fields and the recommended values.

Data Server Implementation

------------------------------------------------------------------------------
; This section will register an IA4HierarchyFolder implementation
for each new 
; folder added to the iSeries Navigator hierarchy.  
 
[HKEY_CLASSES_ROOT\CLSID\{D09970E1-9073-11d0-82BD-08005AA74F5C}]
    @="AS/400 Data Server - Sample Data"
 
[HKEY_CLASSES_ROOT\CLSID\{D09970E1-9073-11d0-82BD-08005AA74F5C}\InprocServer32]
    @="%CLIENTACCESS%\Plugins\IBM.Sample\sampext.dll"
    "ThreadingModel"="Apartment"

If your plug-in will add more than one new folder to the hierarchy, you must duplicate this section of the registry file for each additional folder, making sure to generate a separate GUID for each folder. If your plug-in doesn't add any folders, you can remove this section.

  1. Change the name of the DLL to match the name of the DLL that is generated by your new project workspace.
  2. Generate and copy a new GUID (See the global changes section at the bottom of this page)
  3. Replace both occurrences of the CLSID in this section of the registry with the new GUID string you just generated.
  4. Search for the string "IMPLEMENT_OLECREATE" in your version of the file SAMPDATA.CPP
  5. Paste the new GUID over the existing CLSID in the comment line, then change the CLSID in the IMPLEMENT_OLECREATE macro call to match the hex values in your new GUID. Replace the word "Sample" with the name of your new folder.
  6. Create two new source files for each new GUID, using a renamed copy of SAMPDATA.H and SAMPDATA.CPP as a base.
    Note: The header file (.H) contains the class declaration for the new implementation class. The implementation file (.CPP) contains the code that obtains the data for the new folder.
  7. Replace all occurrences of the class name "CSampleData" in the two source files with a class name that is meaningful in the context of your plug-in.
  8. To add the new implementation files to the project workspace, open the Insert menu and select Files Into Project....
  9. Because you are duplicating SAMPDATA.CPP in this way, all your new folders will initially contain library objects.

Shell plug-in implementation

;--------------------------------------------------------------------
; This section will register the shell plug-in implementation class.
; A shell plug-in adds context menu items and/or property pages 
; for new or existing objects in the hierarchy.
 
[HKEY_CLASSES_ROOT\CLSID\{3D7907A1-9080-11d0-82BD-08005AA74F5C}]
    @="AS/400 Shell plug-ins - Sample"
 
[HKEY_CLASSES_ROOT\CLSID\{3D7907A1-9080-11d0-82BD-08005AA74F5C}\InprocServer32]
    @="%CLIENTACCESS%\Plugins\IBM.Sample\sampext.dll"
    "ThreadingModel"="Apartment"
 
;--------------------------------------------------------------------
; Approve shell plug-in (required under Windows NT(R))
 
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved]
    "{3D7907A1-9080-11d0-82BD-08005AA74F5C}"="AS/400 Shell plug-ins - Sample"

This section registers the shell plug-in implementation class. Every c++ plug-in must use this section.

  1. Change the DLL name to match the name of the DLL that was generated by your new project workspace.
  2. Generate and copy a new GUID (see the global changes section at the bottom of this page).
  3. Replace all occurrences of the CLSID in the entries that are shown in the example above with the new GUID you just generated.
  4. Search for the string "IMPLEMENT_OLECREATE" in your version of the file EXTINTFC.CPP
  5. Paste the new GUID over the existing CLSID in the comment line, then change the CLSID in the IMPLEMENT_OLECREATE macro call to match the hex values in your new GUID.

Shell plug-in implementation for objects

;--------------------------------------------------------------------
; Register a context menu handler for the new folder and its objects
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample\shellex\Sample\*
\ContextMenuHandlers\{3D7907A1-9080-11d0-82BD-08005AA74F5C}]
 
;--------------------------------------------------------------------
; Register a property sheet handler for the new folder and its objects
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.Sample\shellex\Sample\*
\PropertySheetHandlers\{3D7907A1-9080-11d0-82BD-08005AA74F5C}]
 
;--------------------------------------------------------------------
; Register the Auto Refresh property sheet handler for the new folder and its objects
; (this will allow your folder to take advantage of the iSeries Navigator 
;  Auto Refresh function)
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample\shellex\Sample\*
\PropertySheetHandlers\{5E44E520-2F69-11d1-9318-0004AC946C18}]
 
;------------------------------------------------------------------------------

; Register drag and drop context menu handlers
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample\shellex\Sample\*
\DragDropHandlers\{3D7907A1-9080-11d0-82BD-08005AA74F5C}]
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample\shellex\File Systems\*
\DragDropHandlers\{3D7907A1-9080-11d0-82BD-08005AA74F5C}]
 
;------------------------------------------------------------------------------

; Register Drop Handler to accept drops of objects
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY plug-inS\IBM.Sample\shellex\Sample\*\DropHandler]
        @="{3D7907A1-9080-11d0-82BD-08005AA74F5C}"
 
;------------------------------------------------------------------------------

; Register that this plug-in supports Secure Socket Layer (SSL) Connection
; Note:  "Support Level"=dword:00000001   says the plugin supports SSL
; Note:  "Support Level"=dword:00000000   says the plugin does not support SSL
 
[HKEY_CLASSES_ROOT\IBM.AS400.Network\3RD PARTY EXTENSIONS\IBM.Sample\SSL]
"Support Level"=dword:00000001

The final section of the registry specifies which objects in the Navigator hierarchy are affected by implementation of the plug-in.

  1. Replace the CLSID in this section with the new GUIDs.
  2. If your plug-in will not add additional property pages to a property sheet for a folder or object, then remove the registry entry for the property sheet handler.
  3. If your plug-in will not be a drop handler for objects, remove the drag and drop context menu handler and drop handler registry entries.
  4. Edit the subkeys \Sample\*\. For more information see, Shell plug-ins.
  5. Edit or remove the code in your version of EXTINTFC.CPP, that checks for the object types defined by the sample.

    You should see the folders, context menu items, property pages, and drop actions from the sample, depending on how much function from the sample you decided to retain

    Note: The code file based on the sample file EXTINTFC.CPP contains the code that will be called for context menus, property pages, and drop actions. The sample code contains checks for the object types that the sample defines. You must edit this file and either remove these tests or change them to check for the object types for which you wish to provide new function.

Global changes

You have to specify a unique ProgID and GUIDs for use throughout the plug-in registry file.

Define a unique programmatic identifier, or ProgID, for your plug-in:

The ProgID should match the <vendor>.<component> text string, where vendor identifies the name of the vendor who developed the plug-in, and component describes the function being provided. In the sample plug-in, the string "IBM®.Sample" identifies IBM as the vendor, and "Sample" as the description of the function that is provided by the plug-in. This will be used throughout the registry file, and will name the directory where your plug-in will reside on both the iSeries server and the workstation. Replace every occurrence of "IBM.Sample" in the registry file with your ProgID.

Generate new GUIDs, and replace the CLSID values in the registry file:

For your iSeries Navigator C++ plug-in to work properly, you must replace specific CLSIDs in your new registry file with GUIDs that you generate.

The Component Object Model from Microsoft® uses 16-byte hex integers to uniquely identify ActiveX implementation classes and interfaces. These integers are known as GUIDs (Globally Unique Identifiers). GUIDs that identify implementation classes are called CLSIDs. (pronounced "class IDs") iSeries Navigator uses the Windows® ActiveX runtime support to load a plug-in's components, and to obtain a pointer to an instance of the plug-in's implementation of a particular interface. A CLSID in the registry uniquely identifies a specific implementation class that resides in a specific ActiveX server DLL. The first stage of this mapping, from the CLSID to the name and location of the server DLL, is accomplished by means of a registry entry. Therefore, an iSeries Navigator plug-in must register a CLSID for each implementation class that it provides.

Follow these steps to generate your GUIDs:

  1. From the Windows taskbar, select Start and then Run.
  2. Type GUIDGEN and click OK.
  3. Make sure that Registry Format is selected.
  4. To generate a new GUID value, select New GUID.
  5. To copy the new GUID value to the clipboard, select Copy.
Parent topic: Customize the plug-in registry files