IDMActionProvider Interface

Version: 2.0
COM Interface for DM2003 Action providers

GUID: {673A9FB5-9A0B-11D4-B2A4-FD6847C75367}

IDMActionProvider interface implemented by DM2003 action providers. Action provider technology based on COM standards and allows DM2003.EXE application seamlessly extend its user-level functionality. DM2003 loads all registered providers at startup. Correct registration assumes that provider COM object implements a) IDMActionProvider interface and b) CATID_DMActionProvider category. Internally, IDMActionProvider interface used in Delphi code by special action components (TDMUserAction) defined in the DMUserAction.pas unit. Keep in mind that provider should expose action list both at design-time (see DMUserActionEditor.pas) and at run-time.

Action Provider technology allows you to extend DM2003 features beyond possible restrictions of existing ActiveX controls and HTML UI layout. For your convenience, this manual includes  Action Provider examples (Delphi and .Net languages) that illustrates basic implementation of this technology.

Members:
Kind Name Description
InitializeProvider Initialize provider COM object before use
CloseProvider Close provider COM object after use
ConfigureProvider Invoke provider configuration dialog box
GetActionID Return Action ID by index
ActionCount Return the number of implemented actions
GetActionProperties Return description properties (caption etc.)
ExecuteAction Perform action function
UpdateAction Return action status (enabled, checked etc.)

Syntax:
function InitializeProvider(HWnd: THandle; const DMApp: IDispatch): HResult; stdcall;

Provider host application calls this member to initialize provider with the application window handle and DMApplication object reference. Obviously, the provider can't operate normally without these references so that it must be the first interface call. If provider have been initialized normally, this function must return S_OK.

Syntax:
function CloseProvider: HResult; stdcall;

This member terminates provider and releases all resources allocated in the InitializeProvider. The call of CloseProvider function must finish its use.

Syntax:
function ConfigureProvider: HResult; stdcall;

Invokes provider configuration dialog box (if any required). If this member return S_NOTIMPLEMENTED, the host application must display appropriate message box. It's a good idea to provide user with independent configuration option based on RUNDLL32.EXE utility (if possible).

Syntax:
function GetActionID(Action: variant; out ID: WideString): HResult; stdcall;

This member used in conjunction with ActionCount to enumerate available actions. Both these members allow host application (DM2003.EXE or Delphi Object Inspector) to build convenient TDMUserAction editors. At present, Action parameter is a numeric value in range 1..ActionCount. Otherwise, GetActionID must return E_INVALIDARG.

IDs of some standard actions listed here.

Syntax:
function ActionCount(out Count: integer): HResult; stdcall;

Allows host to determine how many actions are supported by provider. As well as GetActionID, this member should be used to configure TDMUserAction objects. In general, ActionCount always expected to return S_OK, while Count parameter may be zero (e.g. if provider fails to initialize).

Syntax:
function WindowCaption(Operation): HResult; stdcall;

Syntax:
function GetActionProperties(Action: variant; out Caption, Hint, HelpKeyword: WideString): HResult; stdcall;

Returns action description attributes. Although TDMUserAction objects do not publish these properties, they read them from the provider when ID property is changed so that linked Delphi components display their captions and hints correctly. Notice that if TDMUserAction object can't call GetActionProperties it reports that it cannot find provider, but if GetActionProperties fails, Hint says that appropriate action is unavailable. Action parameter must be one of those returned by GetActionID.

Syntax:
function ExecuteAction(Action: variant): HResult; stdcall;

Just performs Action whose ID must be one of those returned by GetActionID. This member potentially can raise a lot of exceptions trapped by OleCheck in Delphi code. Of course, ExecuteAction intensively uses host object model for calculations.

Syntax:
function UpdateAction(Action: variant; var State: integer): HResult; stdcall;

Returns action state which, in turn, depends on the states of various objects exposed by host application. The State parameter is a bitwise combination of flags listed in ActionStates enumeration. Please keep in mind that UpdateAction member may be called thousands times per second in the host's message processing loop, so that it must be highly effective.