Export (0) Print
Expand All

COM Reference (Silverlight 1.0)

Silverlight

This topic contains the COM reference for interfaces exposed on the agcore DLL based on Version 1 of Silverlight.

Important noteImportant 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.

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

IXcpControl

IXcpControlDownloadCallback

IXcpControlHost

IXcpObject 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 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 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::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 (Silverlight Plug-in)

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

get_InitParams

IXcpControl Interface

InitParams

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

get_OnError

IXcpControl Interface

OnError

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

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

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

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

Provides a common return type used by CreateObject. This interface defines no additional methods beyond IUnknown and IDispatch

Community Additions

ADD
Show:
© 2014 Microsoft