com.esri.arcgis.system
Interface IExtensionManagerAdmin

All Superinterfaces:
Serializable
All Known Implementing Classes:
ExtensionManager

public interface IExtensionManagerAdmin
extends Serializable

Provides access to members that give life to the extensions.

Remarks

Before you use a licensed extension, you need to load it and enable it. You load the extension using the IExtensionManagerAdmin AddExtension method and passing in the CLSID of the extension. Then before you use the extension, you need to enable it.

To enable the extension, find the extension using the IExtensionManager FindExtension method, obtain IExtensionConfig on the extension, and then set the State property to esriESEnabled. Keep in mind that setting this property may fail, so be prepared to handle that in your application. If enabling the extension succeeds, that means that the license was checked out. If not, then the license could not be acquired.

If during the life of your application, you want to give the license back, simply set the state to esriESDisabled. If that succeeds the license was checked back in. If it failed that means there are outstanding objects (from the extension) that are still using the license.

There is no need to use IExtensionManagerAdmin from within the standard ESRI applications, such as ArcMap, since the loading and unloading of extensions is done automatically. However, you may sometimes control license usage with IExtensionConfig.

When To Use

If you are building an application that makes use of licensed extension functionality like Spatial Analyst, 3D Analyst, or ArcPress, you need to take responsibility for enabling the extension you're using. You can use the IExtensionManagerAdmin interface to control the lifetime of an extension inside your application.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

See Also:
IExtension, IExtensionManager, ExtensionManager, IExtensionManagerAdmin

Method Summary
 void addExtension(IUID extensionCLSID, Object initializationData)
          Creates a single extension given the CLSID, then passes initializationData to IExtension::Startup.
 void shutdownExtensions()
          Shuts down and releases the extensions that are loaded and calls IExtension::Shutdown.
 void startupExtensions(IUID componentCategory, IUID jitCategory, Object initializationData)
          Creates and starts the extensions for the given component category, passing initializationData to each in IExtension::Startup.
 

Method Detail

startupExtensions

void startupExtensions(IUID componentCategory,
                       IUID jitCategory,
                       Object initializationData)
                       throws IOException,
                              AutomationException
Creates and starts the extensions for the given component category, passing initializationData to each in IExtension::Startup.

Description

The StartupExtensions method is similar to AddExtension, except that it operates on all the extensions in the specified component category (for example, ESRI Mx Extensions).

Remarks

It is okay to add extensions to your Application using the AddExtension method after extensions were added with the StartupExtensions method.

You cannot add extensions to your Application using the StartupExtensions method after extensions were added with the AddExtension method. It evokes the "Automation error Catastrophic failure" (-2147418113).

The StartupExtensions method needs to be called before the AddExtensions method or used solely.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
componentCategory - A reference to a com.esri.arcgis.system.IUID (in)
jitCategory - A reference to a com.esri.arcgis.system.IUID (in)
initializationData - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

shutdownExtensions

void shutdownExtensions()
                        throws IOException,
                               AutomationException
Shuts down and releases the extensions that are loaded and calls IExtension::Shutdown.

Description

The ShutdownExtensions method unloads all the extensions from your application and releases the licenses.

Remarks

There is no way to add extensions to your application using the same method, with which extensions were added to it, after the ShutdownExtensions method has been called in the same application lifetime.

Example 1:

Extensions were added with the AddExtension method.

The ShutdownExtensions has been called.

You cannot add extensions using the AddExtension method.

You can add extensions using the StartupExtensions method.

Example 2:

Extensions were added with the StartupExtensions method.

The ShutdownExtensions has been called.

You cannot add extensions using the StartupExtensions method.

You can add extensions using the AddExtension method.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.

addExtension

void addExtension(IUID extensionCLSID,
                  Object initializationData)
                  throws IOException,
                         AutomationException
Creates a single extension given the CLSID, then passes initializationData to IExtension::Startup.

Description

The AddExtension method loads the extension specified by the CLSID. Before using a licensed extension, it needs to be loaded and enabled.

extensionCLSID specifies the unique identifier (UID) of an extension.

To enable the extension, find the extension using the IExtensionManager::FindExtension method, obtain IExtensionConfig on the extension, and then set the State property to esriESEnabled.

To load all the extension within a specified component category (for example, ESRI Mx Extensions) use the StartipExtensions method.

Remarks

COM coclasses are identified by a globally unique identifier (GUID). There two formats for the GUID for a coclass: a class ID (CLSID) and a ProgID. The ProgID is a text alias for a CLSID. The UID coclass can be used to represent the GUID of an extension object. You can set the IUID.Value property to either the CLSID or the ProgID.

To find the CLSID and ProgID of an ESRI extension, refer to the following technical document:

ArcObjects Developer Help > Technical Documents > ESRI Extensions: Names and IDs

For your custom extensions, the ProgID is a string composed of the name of your project used to make the extension and the class name of the extension.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Parameters:
extensionCLSID - A reference to a com.esri.arcgis.system.IUID (in)
initializationData - A Variant (in)
Throws:
IOException - If there are interop problems.
AutomationException - If the ArcObject component throws an exception.