Host Interfaces for Silverlight ActiveX Control for Windows Version 1.0

Structures and Enumerations

XcpHostOptions

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 };

Members

XcpHostOption_FreezeOnInitialFrame   Animation timelines do not progress even if triggered (this implicitly stops AutoPlay videos also). Normal UI painting, initial downloads, and other time-dependent client operations will still proceed as normal. XcpHostOption_DisableFullScreen   Calls to APIs that attempt to run the Silverlight plugin in full-screen mode will silently fail. XcpHostOption_DisableManagedExecution   Not implemented, do not use. XcpHostOption_EnableCrossDomainDownloads   Hosts are generally operating from an assumed full trust, whereas the browser-hosted trust is more restricted. Setting this option allows a host to enable downloads using paths that are normally blocked by a browser-hosted plugin, such as FILE, mixed HTTP/HTTPS, etc.

Visual C++ Reference

IXcpControl IXcpControlDownloadCallback IXcpControlEvents 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 OnFullScreenChange, OnResize, CreateFromXaml, CreateFromXamlDownloader, FindName, ActualHeight, ActualWidth, 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 Interface
• put_InitParams
• InitParams

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 name of a specified scripting handler method that can process any control-specific script level errors raised by the control.

Syntax

HRESULT get_OnError(   BSTR*  phandler );

Parameters

phandler   [out]  The name of the user-defined script handler.

Return Values

The method returns an HRESULT.

See Also

• IXcpControl Interface
• put_OnError

IXcpControl::get_OnLoad

Retrieves the name of a specified scripting handler method that will execute when the onLoad event is raised by the control.

Syntax

HRESULT get_OnLoad(   BSTR*  phandler );

Parameters

phandler   [out]  The name of 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, EnableFramerateCounter, EnableHtmlAccess, EnableRedrawRegions, MaxFrameRate, Windowless.

Return Values

The method returns an HRESULT.

See Also

• IXcpControl Interface
• Using CreateSilverlight.js and Silverlight.js

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 Interface
• put_Source
• put_Source
• Source

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

• get_InitParams
• IXcpControl Interface
• InitParams

IXcpControl::put_OnError

Specifies the name of a scripting handler method that can process any control-specific script level errors raised by the control.

Syntax

HRESULT put_OnError(   BSTR  handler );

Parameters

handler   [in]  The name of a scripting handler method.

Return Values

The method returns an HRESULT.

See Also

• get_OnError
• IXcpControl Interface
• OnError

IXcpControl::put_OnLoad

Specifies the name of a scripting handler method that will execute when the onLoad event is raised by the control.

Syntax

HRESULT put_OnLoad(   BSTR  handler );

Parameters

handler   [in]  The name of a scripting handler method.

Return Values

The method returns an HRESULT.

See Also

• get_OnLoad
• IXcpControl Interface
• OnLoad

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

IXcpControlEvents Interface

Provides a method that returns error results to the host. Other methods are deprecated. In addition to the methods inherited from IDispatch, the IXcpControlEvents interface exposes the following methods. Error Pause Resume Start Stop

IXcpControlEvents::Error

Reports error results that originate from the host plugin to the host.

Syntax

HRESULT Error(   long  line,   long  column,   long  HResult,   BSTR  ErrorString );

Parameters

line   [in]  Line of the error. column   [in]  Column of the error. HResult   [in]  HRESULT from the error. ErrorString   [in]  Descriptive error string.

Return Values

The method returns an HRESULT.

See Also

• IXcpControlEvents Interface

IXcpControlEvents::Pause

Deprecated, do not use.

Syntax

HRESULT Pause();

IXcpControlEvents::Resume

Deprecated, do not use.

Syntax

HRESULT Resume();

IXcpControlEvents::Start

Deprecated, do not use.

Syntax

HRESULT Start();

IXcpControlEvents::Stop

Deprecated, do not use.

Syntax

HRESULT Stop();

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 Silverlight Application Scripting Error Handling). 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.