MORE INFORMATION
The SMS Advanced Client raises various notifications when it receives a request to run a program. This request to run a program may originate in one of the following programs:
- The SMS 2003 software development kit (SDK)
- The Run Advertised Programs item in Control Panel
- The Add or Remove Programs item in Control Panel
These notifications are raised by using the COM+ Event System service.
The notifications inform the user about the current state of the request. The SMS Advanced Client user experience
for software distribution and for software updates is implemented by using these notifications.
You can replace the default SMS Advanced Client user interface elements with your own custom user interface elements by implementing these notifications.
To do this, implement the
IUIEvent interface and expose the
IUIEvent interface by using a DCOM local server.
When you implement the DCOM local server, you must configure it by using the following registry subkey:
HKEY_LOCAL_MACHINE\Software\Microsoft\SMS\MObile Client\Configuration\UIServer
When you implement custom user interface elements, the following actions occur:
- If a custom UI server is configured under this registry subkey, SMS tries to initialize it and then subscribes to these notifications.
- If a custom UI server is configured under this registry subkey, but the initialization fails, SMS falls back to the default UI server.
- If no custom UI server is configured under this registry subkey, SMS uses the default UI server.
Note We do not support the use of a custom UI server for the Run Advertised Programs monitor or for the Program Download Monitor component.
Built-in UI elements
The following table lists the built-in UI elements that perform calls to the default UI server.
|
| ClearNewAppAvailable | Called whenever a user opens Add or Remove Programs |
| ClearNewScriptAvailable | Called whenever a user opens Run Advertised Programs |
| ClearSoftwareUpdate | Called when no more software updates are available to install on a client computer |
| ContentStatus | Called in response to a request from CheckContentAvailability |
| DownloadComplete | Called when the Advanced Client finishes downloading the content of a program locally |
| DownloadFailed | Called when the Advanced Client cannot locally download the content of a program |
| DownloadStarted | Called whenever the Advanced Client starts locally downloading the content of a program |
| DownloadProgress | Informs the user about the current progress of a requested content download |
| ExecutionFailed | Called if the program that is started by the Advanced Client returns a failure |
| LogoffRequired | Called when the Advanced Client runs a program that requires that a user log off after the program successfully finishes |
| NewAppAvailable | Called when an SMS administrator advertises an optional program that becomes available in Add or Remove Programs |
| NewScriptAvailable | Called when an SMS administrator advertises an optional program that becomes available in Run Advertised Programs |
| ReadyAssignedProgram | Called when a mandatory program is ready to run |
| ReadyUserProgram | Called when an optional program that requires downloading is ready to run after the download operation finishes |
| RebootRequired | Called when the Advanced Client runs a program that requires a restart after the program successfully finishes |
| RunInstallProgram | Called when a user selects an optional program to run from Add or Remove Programs or Run Advertised Programs |
| ShowMessage | Never called |
| ShowProgramDownloadMonitor | Called when a user starts the program download monitor by using Control Panel |
| SoftwareUpdateAvailable | Called when pending software updates must be installed on a client computer |
| SoftwareUpdateProgress | Called in response to a user's request to install pending software updates |
| UserInitialize | Called every time that a user logs on to a computer |
Enumerations and structures that IUIEvent uses
|
| tagContentStatus |
| tagSWUPDATE_SCHEDULE_TYPE |
| tagSWUPDATE_STATE
|
| tagUI_MESSAGE_TYPE |
Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.
You can use the following interface definition file to obtain the methods and the structure descriptions for IUIEvent.
/----- Start of IDL file-------/
// MyUIserver.idl : IDL source for MyUIserver
// Sample Custom UI COM server based on SMS 2003 SP1 SDK documentation.
// This is a sample to illustrate how a custom UI server should look.
// It is not fully tested. Do not use it in a production environment.
//
// -------------------------------------------------------------------------------------------------------------
// This file will be processed by the MIDL tool to
// produce the type library (myuiserver.tlb) and marshaling code.
import "oaidl.idl";
import "ocidl.idl";
typedef [v1_enum] enum tagUI_MESSAGE_TYPE
{
UI_MESSAGE_ERROR = 0x00000000,
UI_MESSAGE_WARNING = 0x00000001,
UI_MESSAGE_UNKNOWN = 0x00000002,
} UI_MESSAGE_TYPE;
typedef [v1_enum] enum tagSWUPDATE_SCHEDULE_TYPE
{
SCHEDULE_NONE = 0x00000000,
SCHEDULE_REBOOT = 0x00000001,
SCHEDULE_RECURRENCE = 0x00000002,
SCHEDULE_MANDATORY = 0x00000003,
SCHEDULE_USERDEFINED = 0x00000004,
} SWUPDATE_SCHEDULE_TYPE;
typedef [v1_enum] enum tagSWUPDATE_STATE
{
UPDATE_AVAILABLE = 0x00000000,
UPDATE_STARTED = 0x00000001,
UPDATE_SCANNING = 0x00000002,
UPDATE_FAILED = 0x00000003,
UPDATE_WAITING = 0x00000004,
UPDATE_NONE = 0x00000005,
} SWUPDATE_STATE;
typedef [v1_enum] enum tagContentStatus
{
CNTNT_NOT_AVAILABLE = 0x00000000,
CNTNT_RQRS_DWNLD = 0x00000001,
CNTNT_RQRS_OOBMEDIA = 0x00000002,
CNTNT_RQRS_OOBMEDIA_DWNLD = 0x00000003,
CNTNT_AVAILABLE = 0x00000004,
} eContentStatus;
[
object,
// Do not change this UUID. If you modify this UUID, SMS cannot locate the interface
uuid(C529A879-369D-428C-82AC-AFF79A3ADC37),
dual,
nonextensible,
helpstring("IUIEvents Interface"),
pointer_default(unique)
]
interface IUIEvents : IDispatch{
[id(1), helpstring("method UserInitialize")] HRESULT UserInitialize();
[id(2), helpstring("method NewAppAvailable")] HRESULT NewAppAvailable();
[id(3), helpstring("method NewScriptAvailable")] HRESULT NewScriptAvailable();
[id(4), helpstring("method DownloadProgress")] HRESULT DownloadProgress(BSTR sPackageID, [in] long nCurrentSize, [in] long nTotalSize);
[id(5), helpstring("method DownloadComplete")] HRESULT DownloadComplete([in] BSTR sProgramID, [in] BSTR sPackageID);
[id(6), helpstring("method DownloadFailed")] HRESULT DownloadFailed([in] BSTR sProgramID, [in] BSTR sPackageID, [in] long nReasonCode);
[id(7), helpstring("method RebootRequired")] HRESULT RebootRequired([in] long nCountDown, [in] long nFinalInterval);
[id(8), helpstring("method LogoffRequired")] HRESULT LogoffRequired([in] long nCountDown, [in] long nFinalInterval);
[id(10), helpstring("method ReadyAssignedProgram")] HRESULT ReadyAssignedProgram([in] BSTR sProgramID, [in] BSTR sPackageID, [in] long nCountDown);
[id(11), helpstring("method ReadyUserProgram")] HRESULT ReadyUserProgram([in] BSTR sProgramID, [in] BSTR sPackageID, [in] BOOL bRunOnCompletion);
[id(13), helpstring("method ClearNewAppAvailable")] HRESULT ClearNewAppAvailable();
[id(14), helpstring("method ClearNewScriptAvailable")] HRESULT ClearNewScriptAvailable();
[id(15), helpstring("method ContentStatus")] HRESULT ContentStatus([in] BSTR sCntntRqstID, [in] eContentStatus eStatus);
[id(16), helpstring("method RunInstallProgram")] HRESULT RunInstallProgram([in] BSTR sProgramID, [in] BSTR sPackageID, [in] BOOL bInstallsApp);
[id(18), helpstring("method DownloadStarted")] HRESULT DownloadStarted([in] BSTR sProgramID, [in] BSTR sPackageID, [in] BOOL bRunOnCompletion, [in] BSTR sDependentProgID, [in] BSTR sDependentPkgID);
[id(19), helpstring("method ExecutionFailed")] HRESULT ExecutionFailed([in] BSTR sProgramID, [in] BSTR sPackageID, [in] VARIANT sDependentProgIDs, [in] VARIANT sDependentPkgIDs, [in] long nReasonCode);
[id(20), helpstring("method ShowProgramDownloadMonitor")] HRESULT ShowProgramDownloadMonitor();
[id(21), helpstring("method ShowMessage")] HRESULT ShowMessage([in] BSTR sTitle, [in] BSTR sText, [in] UI_MESSAGE_TYPE eMsgType);
[id(22), helpstring("method SoftwareUpdateAvailable")] HRESULT SoftwareUpdateAvailable([in] SWUPDATE_SCHEDULE_TYPE eScheduleType, [in] long nScheduleTime, [in] BSTR sBrandingText, [in] BOOL bInstallUpdates);
[id(23), helpstring("method SoftwareUpdateProgress")] HRESULT SoftwareUpdateProgress([in] SWUPDATE_STATE eUpdateState);
[id(24), helpstring("method ClearSoftwareUpdate")] HRESULT ClearSoftwareUpdate([in] long nWaitTime);
[id(25), helpstring("method SoftwareUpdatesInstall")] HRESULT SoftwareUpdatesInstall([in] long nCountDown, [in] BSTR sNextSchedule, [in] BSTR sMandatoryTime, [in] BSTR sITOrg, [in] BSTR sSummaryFile, [in] BSTR sUpdatesInfoFile, [in] BOOL bDefaultToPostpone, [in] BOOL bAllowReschedule, [in] BOOL bDefaultToBalloon);
[id(26), helpstring("method SoftwareUpdatesInstallProgress")] HRESULT SoftwareUpdatesInstallProgress([in] BSTR sMandatoryTime, [in] BSTR sITOrg, [in] BSTR sSummaryFile, [in] BSTR sUpdatesInfoFile, [in] BOOL bDefaultToBalloon, [in] long nTotalPatchCount, [in] long nProcessedPatchCount, [in] long nFailSafeTimeout);
[id(27), helpstring("method SoftwareUpdatesInstallComplete")] HRESULT SoftwareUpdatesInstallComplete([in] BSTR sITOrg, [in] BSTR sSummaryFile, [in] BSTR sUpdatesInfoFile, [in] BOOL bRebootRequired, [in] BOOL bDefaultToBalloon, [in] BOOL bChangeWindowExpired);
[id(28), helpstring("method SoftwareUpdatesReboot")] HRESULT SoftwareUpdatesReboot([in] BOOL bPreInstallReboot, [in] BOOL bForcedReboot, [in] long nCountDown, [in] BSTR sNextSchedule, [in] BSTR sMandatoryTime, [in] BSTR sITOrg, [in] BSTR sSummaryFile, [in] BSTR sUpdatesInfoFile, [in] BOOL bDefaultToPostpone, [in] BOOL bAllowReschedule, [in] BOOL bDefaultToBalloon);
};
[
uuid(8A1B1E44-75E0-4982-BDBB-37771AFE1270),
version(1.0),
helpstring("myuiserver 1.0 Type Library")
]
library myuiserverLib
{
importlib("stdole2.tlb");
[
uuid(56E597C2-29D8-465B-A569-8CF9FA7409B7),
helpstring("myuiservercls Class")
]
coclass myuiservercls
{
[default] interface IUIEvents;
};
};
/----- end of IDL file-------/
Using the MyUIserver example to create a custom UI server
Warning Serious problems might occur if you modify the registry incorrectly by using Registry Editor or by using another method. These problems might require that you reinstall your operating system. Microsoft cannot guarantee that these problems can be solved. Modify the registry at your own risk.
To create a custom UI server by using the example code, follow these steps:
- Create a custom out-of-process UI server that implements the IUIEvent interface.
- Register the UI server in the operating system. For example, run a command that resembles the following:
myuiserver.exe /regserver
- Register the Proxy Stub .dll file. For example, run a command that resembles the following:
regsvr32 myuiserverps.dll
- Configure the server identity to run in the Interactive user object in Component Services.
- Add the UI server CLSID value to the following registry subkey:
HKLM\Software\Microsoft\SMS\MObile Client\Configuration\UIServer
C4F23AE4-82D8-456F-A4AF-A2655D8CA837
- Advertise a new program to the client computer.
Note if you want to run this example program on a computer on which Microsoft Visual Studio is not installed, you must copy the Msvcr71.dll file to the computer. This example program requires Msvcr71.dll.
To determine whether the UI server successfully initialized, examine the Execmgr.log file. If a problem occurred with the UI server initialization, entries that resemble the following appear are logged:
Failed to instantiate UI Server with error <error entry>
If no error entries appear in this log file, SMS is using the UI server. In this situation, examine the C:\MyUIserver.log file. This log file displays the method that was started together with the corresponding date and time.
For more information about the IUIEvent interface, visit the following Microsoft Web site:
To obtain the SMS 2003 SDK, visit the following Microsoft Web site: