IMAPIFormContainer::InstallForm

The IMAPIFormContainer::InstallForm method installs a form into a form container.

Quick Info

See IMAPIFormContainer : IUnknownUYR5A.

HRESULT InstallForm(

Parameters

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the client application sets the MAPI_DIALOG flag in the ulFlags parameter. The ulUIParam parameter can be NULL if MAPI_DIALOG is not also passed.

ulFlags

[in] Bitmask of flags that controls the installation of the form. The following flags can be set:

MAPI_DIALOG

Displays a dialog box to provide progress information or prompt the user for additional information. If this flag is not set, no dialog box is displayed.

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

MAPIFORM_INSTALL_OVERWRITEONCONFLICT

A previous definition of the form is to be replaced with the definition of the form being installed. This flag is ignored when MAPI_DIALOG is present. 

szCfgPathName

[in] Path to the form configuration file that describes the form and its implementation.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_EXTENDED_ERROR

An implementation error occurred; to get the MAPIERROR4GS6AI structure associated with the error, call the IMAPIFormContainer::GetLastError method.

MAPI_E_USER_CANCEL

The user canceled the installation of the form, typically by clicking the Cancel button in a dialog box.

Notes to Callers

Client applications call the IMAPIFormContainer::InstallForm method to install a form into a specific form container. The szCfgPathName parameter must contain the path of a form configuration file   that is, a file with the .CFG extension   that describes the form and its implementation. The ulFlags parameter specifies:

    That a user interface enabling the user installing the form to specify details of installation is displayed, if the MAPI_DIALOG flag is set.

    That the previous form definition is overlaid with the form being installed, if the MAPIFORM_INSTALL_OVERWRITEONCONFLICT flag is set. Otherwise, the form installation is merged with the current form description, if one exists.

    That MAPIFORM_INSTALL_OVERWRITEONCONFLICT is ignored when MAPI_DIALOG is present.

    That the absence of MAPIFORM_INSTALL_OVERWRITEONCONFLICT in the flag set means that a merge will be done. Any new platforms in the .CFG file not currently present in the form description will be installed and no other changes will take place.

    That the path to the form configuration file is a Unicode string, if the MAPI_UNICODE flag is set.

Clients should call IMAPIFormContainer::GetLastError if InstallForm returns MAPI_E_EXTENDED_ERROR and should check the returned MAPIERROR4GS6AI structure to determine the condition causing the error.

Notes to Implementers

Form library providers should fill in a MAPIERROR structure and return MAPI_E_EXTENDED_ERROR if any of the following conditions occur:

    The configuration file is not found.

    The configuration file is not readable.

    The configuration file is invalid.