COM Reference (Silverlight 1.0)
Microsoft Silverlight will reach end of support after October 2021. Learn more.
This topic contains the COM reference for interfaces exposed on the agcore DLL based on Version 1 of Silverlight.
COM Interfaces Have Been Updated
.gif "Important note") Important Note: |
|---|
This topic specifically documents the COM interfaces that were available in version 1.0. Additional interfaces have been added, and using the updated interfaces is required if you intend to address features introduced in Silverlight 2 such as splash screens. See COM Reference. |
If you specifically want to use the Version 1 interfaces only, these interface prototypes are available in an IDL file that can be obtained from the Microsoft Download Center. The interfaces as found in that IDL file are documented in this topic.
Structures and Enumerations
XcpHostOptions
Specifies runtime options that are applied against the hosted Silverlight control when an instance is created.
Syntax
typedef enum XcpHostOptions{
XcpHostOption_FreezeOnInitialFrame =0x01,
XcpHostOption_DisableFullScreen =0x02,
XcpHostOption_DisableManagedExecution =0x08,
XcpHostOption_EnableCrossDomainDownloads =0x10
};
Visual C++ Reference
IXcpControl
IXcpControlDownloadCallback
IXcpControlHost
IXcpObject Interface
IXcpControl Interface
Creates a Silverlight control, and exposes the parameters that are available to its HTML scripting CreateObject method.
In addition to the methods inherited from IDispatch, the IXcpControl Interface exposes the following methods.
CreateObject
get_Content
get_InitParams
get_IsLoaded
get_OnError
get_OnLoad
get_Settings
get_Source
put_InitParams
put_OnError
put_OnLoad
put_Source
Remarks
All methods of this interface are exposed to scripting, and specific implementation details are often documented in the equivalent script reference.
IXcpControl::CreateObject
Creates a new instance of a Silverlight helper object.
Syntax
HRESULT CreateObject(
BSTR id,
IXcpObject** ppDisp
);
Parameters
id
[in] Specifies the type of control to create.
ppDisp
[out] Pointer to a pointer to the resulting control.
Return Values
The method returns an HRESULT.
Remarks
See CreateObject. The only supported control is Downloader.
See Also
IXcpControl Interface
IXcpControl::get_Content
Gets the content sub-object.
Syntax
HRESULT get_Content(
IDispatch** pContent
);
Parameters
pContent
[out] Pointer to the content sub-object.
Return Values
The method returns an HRESULT.
Remarks
See documentation for OnFullScreenChanged, OnResize, CreateFromXaml, CreateFromXamlDownloader, FindName (Silverlight Plug-in), ActualHeight (Silverlight Plug-in), ActualWidth (Silverlight Plug-in), FullScreen.
See Also
IXcpControl Interface
IXcpControl::get_InitParams
Retrieves any previously specified user-defined initialization parameters.
Syntax
HRESULT get_InitParams(
BSTR* initparams
);
Parameters
initparams
[out] A comma delimited string of initialization tokens.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::get_IsLoaded
Retrieves a Boolean that declares whether the control's onLoad event has been raised.
Syntax
HRESULT get_IsLoaded(
VARIANT_BOOL* pb
);
Parameters
pb
[out] true if the control has raised its onLoad event; otherwise, false.
Return Values
The method returns an HRESULT.
See Also
IXcpControl Interface
IXcpControl::get_OnError
Retrieves the specified scripting handler method that can process any control-specific script level errors raised by the control.
Syntax
HRESULT get_OnError(
VARIANT* pVAR
);
Parameters
pVAR
[out] A user-defined script handler.
Return Values
The method returns an HRESULT.
See Also
IXcpControl Interface
put_OnError
IXcpControl::get_OnLoad
Retrieves the specified scripting handler method that will execute when the onLoad event is raised by the control.
Syntax
HRESULT get_OnLoad(
VARIANT* pVAR
);
Parameters
pVAR
[out] The user-defined script handler.
Return Values
The method returns an HRESULT.
See Also
IXcpControl Interface
put_OnLoad
IXcpControl::get_Settings
Retrieves settings from the browser.
Syntax
HRESULT get_Settings(
IDispatch** pSettings
);
Parameters
pSettings
[out] Pointer to a sub-object containing the plugin settings. See documentation for Background (Silverlight Plug-in), EnableFramerateCounter, EnableHtmlAccess, EnableRedrawRegions, MaxFrameRate, Windowless.
Return Values
The method returns an HRESULT.
See Also
IXcpControl Interface
IXcpControl::get_Source
Retrieves the URI specified for the source XAML.
Syntax
HRESULT get_Source(
BSTR* pstr
);
Parameters
pstr
[out] The URI specified for the source XAML.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::IsVersionSupported
Determines whether the existing Silverlight plug-in is a matching version or is a compatible version with a specified version string.
Syntax
HRESULT IsVersionSupported(
BSTR v,
VARIANT_BOOL *pb
);
Parameters
v
[in] String specifying the version to check. See IsVersionSupported for format.
pb
[out] Pointer to the returned result. true if the version is supported, otherwise false.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::put_InitParams
Specifies user-defined initialization parameters.
Syntax
HRESULT put_InitParams(
BSTR initparams
);
Parameters
initparams
[in] A comma delimited string of initialization parameters.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::put_OnError
Specifies the scripting handler method that can process any control-specific script level errors raised by the control.
Syntax
HRESULT put_OnError(
VARIANT* pVAR
);
Parameters
pVAR
[in] The scripting handler method.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::put_OnLoad
Specifies a scripting handler method that will execute when the onLoad event is raised by the control.
Syntax
HRESULT put_OnLoad(
VARIANT* pVAR
);
Parameters
pVAR
[in] The scripting handler method.
Return Values
The method returns an HRESULT.
See Also
IXcpControl::put_Source
Specifies the URI to use for the source XAML.
Syntax
HRESULT put_Source(
BSTR str
);
Parameters
str
[in] The URI to use for the source XAML.
Return Values
The method returns an HRESULT.
See Also
get_Source
IXcpControl Interface
IXcpControlDownloadCallback Interface
Implemented by the hosted control to provide a particular DownloadUrl behavior.
In addition to the methods inherited from IUnknown, the IXcpControlDownloadCallback interface exposes the following methods.
OnUrlDownloaded
IXcpControlDownloadCallback::OnUrlDownloaded
Provides a control-implemented callback that should be used for cases where the host wants to process download requests.
Syntax
HRESULT OnUrlDownloaded(
HRESULT hr,
IStream* pStream
);
Parameters
hr
The HRESULT from DownloadURL.
pStream
Pointer to a stream object.
Return Values
The method returns an HRESULT.
Remarks
For cases where the host's DownloadURL implementation returns E_PENDING, call this method from the retrieved interface and pass the end result download stream to pStream to complete the download cycle..
See Also
IXcpControlDownloadCallback Interface
IXcpControlHost Interface
The hosted control queries for the IXcpControlHost interface whenever it is created. Hosts should implement the IXcpControlHost interface to provide hooks that the hosted control will use to modify its behavior when it is hosted by that particular host.
In addition to the methods inherited from IUnknown, the IXcpControlHost interface exposes the following methods.
DownloadUrl
GetBaseUrl
GetHostOptions
GetNamedSource
InvokeHandler
NotifyError
NotifyLoaded
IXcpControlHost::DownloadUrl
Called by the hosted control whenever a download is requested. Hosts should implement this method to provide specialized download behavior for cases where the download might request cross-domain URLs.
Syntax
HRESULT DownloadUrl(
BSTR bstrUrl,
IXcpControlDownloadCallback* pCallback,
IStream** ppStream
);
Parameters
bstrUrl
[in] The url to download.
pCallback
[in] Pointer to the downloader callback implementation.
ppStream
[out] Pointer to a pointer to a stream object.
Return Values
The method returns an HRESULT. HRESULTs have the following meaning to the hosted control:
S_OK
The method succeeded. Content is returned in the stream.
S_FALSE
Always use the hosted control's inherent downloader.
E_FAIL
Do not download any content. The hosted control will raise appropriate errors and events in response to a failed download.
E_PENDING
The host holds on to the callback passed as pCallback, and calls the OnUrlDownloaded method on the callback interface.
Remarks
For the E_PENDING case you should keep a reference to the callback, obtain the stream through your own means (which can be asynchronous), call OnUrlDownloaded on the callback passing that stream, and then release the callback.
See Also
IXcpControlHost Interface
IXcpControlHost::GetBaseUrl
Retrieves the URL that the hosted control should use as the base for any relative requests made for Source, to the downloader, etc.
Syntax
HRESULT GetBaseUrl(
BSTR* pbstrUrl
);
Parameters
pbstrUrl
[out] Pointer to a string containing the intended base URL.
Return Values
The method returns an HRESULT.
Remarks
Typically, Silverlight URIs are given as relative URIs, because only the MediaElement Source property supports cross-domain references (and that does not involve the downloader directly, only indirectly). This property enables you to change what is considered the base URI from which relative URIs are considered.
See Also
IXcpControlHost Interface
IXcpControlHost::GetHostOptions
Retrieves the XcpHostOptions specified by the host.
Syntax
HRESULT GetHostOptions(
DWORD* pdwOptions
);
Parameters
pdwOptions
[out] Pointer to a double word containing the XcpHostOptions.
Return Values
The method returns an HRESULT.
See Also
IXcpControlHost Interface
IXcpControlHost::GetNamedSource
Retrieves the XAML source for cases where the control uses a Source value specified by ID rather than by file.
Syntax
HRESULT GetNamedSource(
BSTR bstrSourceName,
BSTR* pbstrSource
);
Parameters
bstrSourceName
[in] The source ID.
pbstrSource
[out] A string containing the complete XAML source.
Return Values
The method returns an HRESULT.
See Also
IXcpControlHost Interface
IXcpControlHost::InvokeHandler
Invoked whenever events occur within the XAML DOM of the hosted control.
Syntax
HRESULT InvokeHandler(
BSTR bstrName,
VARIANT varArg1,
VARIANT varArg2,
VARIANT* pvarResult
);
Parameters
bstrName
[in] Name of the event.
varArg1
[in] Sender of the event.
varArg2
[in] Arguments of the event.
pvarResult
[out] Return value of the event.
Return Values
The method returns an HRESULT.
Remarks
Silverlight does not perform any inherent event handler hookup, and instead leaves that aspect to the browser script engines. Therefore the control exposes this deliberately language agnostic approach towards event handler invocation. Hosts can use this facility to react to Silverlight-originated events in their own code.
See Also
IXcpControlHost Interface
IXcpControlHost::NotifyError
Invoked whenever errors are raised from within the XAML DOM of the hosted control.
Syntax
HRESULT NotifyError(
BSTR bstrError,
BSTR bstrSource,
long nLine,
long nColumn
);
Parameters
bstrError
[in] The name of the error (see Error Handling (Silverlight 1.0)).
bstrSource
[in] Name of the source XAML file.
nLine
[in] The line number.
nColumn
[in] The column number.
Return Values
The method returns an HRESULT.
See Also
IXcpControlHost Interface
IXcpControlHost::NotifyLoaded
Invoked whenever the XAML DOM has successfully loaded.
Syntax
HRESULT NotifyLoaded();
Parameters
This method takes no parameters.
Return Values
The method returns an HRESULT.
See Also
IXcpControlHost Interface
IXcpObject Interface
Provides a common return type used by CreateObject. This interface defines no additional methods beyond IUnknown and IDispatch