COM Reference

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Silverlight provides a set of COM interfaces on the Internet Explorer version of the plug-in (agcore.dll) and another set that is available for either COM or NPAPI control models.

For more information about using these interfaces, see Alternative Hosting.

AgCore.dll COM Interfaces

The following interfaces are supported only for Internet Explorer and Microsoft Windows in combination. These interfaces are used for hosting the Silverlight plug-in within an application, rather than by using a browser's COM or NPAPI control models to embed Silverlight as part of an HTML page loaded by a browser. The interface definition for these interfaces can be found in the file xcpctrl.idl.

IXcpControl

IXcpControl2

IXcpControlDownloadCallback

IXcpControlHost

IXcpControlHost2

IXcpControlHost3

IXcpObject Interface

XcpHostOptions

XcpHost_GetComAutomationObjectFlags

IXcpControl Interface

Creates a Silverlight plug-in and exposes the parameters that are available to HTML scripting.

In addition to the methods inherited from IDispatch, the IXcpControl interface exposes the following methods.

CreateObject

IsVersionSupported

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 object is Downloader.

In the Silverlight managed API, Downloader is not available. Use WebClient instead.

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::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

IXcpControl::get_InitParams

Retrieves defined initialization parameters.

Syntax

HRESULT get_InitParams(
  BSTR*  initparams
);

Parameters

initparams

  [out]  A string of initialization tokens. The common format for the string (which is expected for end-point parsing into the managed API dictionary representation) is key1=value1,key2=value2, etc.

Return Values

The method returns an HRESULT.

See Also

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.

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

put_OnError

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

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 plug-in settings. See documentation for Background, EnableFramerateCounter, EnableHtmlAccess, EnableRedrawRegions, MaxFrameRate, Windowless.

Return Values

The method returns an HRESULT.

See Also

IXcpControl::get_Source

Retrieves the URI specified for the source content (can be a XAML page or a package, depending on which programming model is used for the Silverlight content).

Syntax

HRESULT get_Source(
  BSTR*  pstr
);

Parameters

pstr

  [out]  The URI specified for the source.

Return Values

The method returns an HRESULT.

See Also

put_Source

Source

IXcpControl::put_InitParams

Specifies user-defined initialization parameters.

Syntax

HRESULT put_InitParams(
  BSTR  initparams
);

Parameters

initparams

  [in]  A string of initialization tokens. The common format for the string (which is expected for end-point parsing into the managed API dictionary representation) is key1=value1,key2=value2, etc.

Return Values

The method returns an HRESULT.

See Also

get_InitParams

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

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

OnLoad

IXcpControl::put_Source

Specifies the URI to use for the source content (the URI can reference a XAML page or a package, depending on whether you are using the JavaScript API or managed API respectively).

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

Source

IXcpControl2 Interface

Extends IXcpControl and exposes the parameters that are available to HTML scripting.

In addition to the methods inherited from IDispatch and IXcpControl, the IXcpControl2 interface exposes the following methods.

LoadRuntime

get_OnSourceDownloadComplete

get_OnSourceDownloadProgressChanged

get_SplashScreenSource

put_OnSourceDownloadComplete

put_OnSourceDownloadProgressChanged

put_SplashScreenSource

Remarks

All methods of this interface are exposed to scripting, and specific implementation details are often documented in the equivalent script reference.

IXcpControl2::LoadRuntime

Loads the CLR runtime.

Syntax

HRESULT LoadRuntime();

Parameters

None.

Return Values

The method returns an HRESULT.

Remarks

Only relevant for an application that uses a XAP as source and thus requires the CLR. Host containers can indicate to load the core CLR runtime using a LoadRuntime call, at a time of their choosing. Otherwise, the CLR is loaded and the AppDomain is initialized when Silverlight processes the XAP file.

IXcpControl2::get_OnSourceDownloadComplete

Retrieves the specified scripting handler method that will execute when the onSourceDownloadComplete event is raised by the control.

Syntax

HRESULT get_OnSourceDownloadComplete(
   VARIANT*  pVAR
);

Parameters

pVAR

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

Return Values

The method returns an HRESULT.

See Also

IXcpControl2::get_OnSourceDownloadProgressChanged

Retrieves the specified scripting handler method that will execute when the onSourceDownloadProgressChanged event is raised by the control.

Syntax

HRESULT get_OnSourceDownloadProgressChanged(
   VARIANT*  pVAR
);

Parameters

pVAR

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

Return Values

The method returns an HRESULT.

See Also

IXcpControl2::get_SplashScreenSource

Retrieves the URI specified for the splash screen source XAML.

Syntax

HRESULT get_SplashScreenSource(
  BSTR*  pstr
);

Parameters

pstr

  [out]  The URI specified for the splash screen source XAML.

Return Values

The method returns an HRESULT.

See Also

IXcpControl2::put_OnSourceDownloadComplete

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

Syntax

HRESULT put_OnSourceDownloadComplete(
  VARIANT*  pVAR
);

Parameters

pVAR

  [in]  The scripting handler method.

Return Values

The method returns an HRESULT.

IXcpControl2::put_OnSourceDownloadProgressChanged

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

Syntax

HRESULT put_OnSourceDownloadProgressChanged(
  VARIANT*  pVAR
);

Parameters

pVAR

  [in]  The scripting handler method.

Return Values

The method returns an HRESULT.

IXcpControl2::put_SplashScreenSource

Specifies the URI to use for the splash screen XAML.

Syntax

HRESULT put_SplashScreenSource(
  BSTR  str
);

Parameters

str

  [in]  The URI to use for the splash screen XAML.

Return Values

The method returns an HRESULT.

See Also

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 method.

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.

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, or where the host has other restrictions on requests made as a URI.

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.

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. This property enables you to change what is considered the base URI from which relative URIs are resolved.

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.

IXcpControlHost::GetNamedSource

Retrieves the source for cases where the control uses a Source value specified by ID (inline XAML) 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.

Remarks

Inline XAML as Source is rare in the JavaScript API and is totally unsupported by the managed API.

IXcpControlHost::InvokeHandler

Invoked whenever events occur within the object model 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

The JavaScript API for 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-neutral approach to event handler invocation. Hosts can use this facility to react to Silverlight-originated events in their own code. Note that the events in question must have the ability to have handlers attached specifically in the control's loaded XAML and must be available in the JavaScript API (otherwise the pathway that exposes event handling to the browser host is not used; managed events are dealt with internally and not raised to the host). The main scenario for InvokeHandler is input events such as KeyDown, MouseLeftButtonDown, etc.

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 Plug-in Error Messages).

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.

IXcpControlHost::NotifyLoaded

Invoked whenever the XAML DOM has successfully loaded.

Syntax

HRESULT NotifyLoaded();

Parameters

None.

Return Values

The method returns an HRESULT.

IXcpControlHost2 Interface

Provides application domain support and other support.

interface IXcpControlHost2 : IXcpControlHost

In addition to the methods inherited from IUnknown andIXcpControlHost , the IXcpControlHost2 interface exposes the following methods.

GetCustomAppDomain

GetControlVersion

IXcpControlHost2::GetCustomAppDomain

Provides application domain support.

HRESULT GetCustomAppDomain(
  IUnknown** ppAppDomain
);

Parameters

ppAppDomain

  [out]  Pointer to a pointer to the custom application domain.

Return Values

The method returns an HRESULT.

Remarks

If UseCustomAppDomain is specified as a flag in the GetHostOptions return value, then GetCustomAppDomain is called to retrieve the custom AppDomain.

In non-hosted cases, Silverlight uses the standard AppDomain.

Most hosts will not use this option; in particular the AppDomain concept is not relevant for many hosting models. Hosts might consider using an AppDomain if they already maintain a custom AppDomain themselves, or want to deliberately use an add-in model for the hosted AppDomain.

IXcpControlHost2::GetControlVersion

Returns version information about the installed Silverlight plug-in.

HRESULT GetControlVersion(
  UINT *puMajorVersion,
  UINT *puMinorVersion
);

Parameters

puMajorVersion

  [out]  The integer value for the major version number of the installed Silverlight plug-in.

puMinorVersion

  [out]  The integer value for the minor version number of the installed Silverlight plug-in.

Return Values

The method returns an HRESULT.

Remarks

See Silverlight Plug-in Versioning for details on the version format.

IXcpControlHost3 Interface

Enables hosts to provide custom theme, font, and Automation support to hosted Silverlight plug-ins.

interface IXcpControlHost3 : IXcpControlHost2

In addition to the methods inherited from IUnknown and IXcpControlHost2 the IXcpControlHost3 interface exposes the following methods.

GetComAutomationObject

GetDefaultPortableUserInterfaceFontInfo

GetDefaultThemeXaml

IXcpControlHost3::GetComAutomationObject

Provides access to the Automation object with the specified progId.

HRESULT GetComAutomationObject(
  BSTR bstrProgId, 
  DWORD dwFlags, 
  IDispatch** ppDisp
); 

Parameters

bstrProgId

  [in]  String specifying the programmatic identifier (progId) of the object to get.

dwFlags

  [in]  Double word containing the Xcp_GetComAutomationObjectFlags.

ppDisp

  [out, retval]  Pointer to a pointer to the resulting Automation 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 through the ppDisp pointer.

S_FALSE

The hosted Silverlight plug-in should use the default mechanism for retrieving Automation objects.

Remarks

This method enables a host to intercept calls from hosted applications to the AutomationFactory.GetObject and CreateObject methods. This is useful to provide Automation support directly within the host application without requiring separate installation and registration of the required Automation servers.

The host can use the dwFlags value to determine which AutomationFactory method was called. If the host can supply an Automation object for the specified bstrProgId value, it should set the ppDisp value and return S_OK. Otherwise, it should return S_FALSE to enable Silverlight to use its default Automation support.

To enable Automation support through this method, the following conditions are required:

  • The hosted application must request elevated permissions in its application manifest.

  • The host must include the EnableElevatedPermissions and HookGetComAutomationObject flags in the GetHostOptions return value.

  • The computer's group policy settings must not prevent trusted applications from running.

For more information, see Trusted Applications and How to: Use Automation in Trusted Applications.

IXcpControlHost3::GetDefaultPortableUserInterfaceFontInfo

Provides the host-specific default composite font if available.

HRESULT GetDefaultPortableUserInterfaceFontInfo(
  LPBSTR pbstrCompositeFont
); 

Parameters

bstrCompositeFont

  [out, retval]  String specifying the composite font to use or null if the hosted plug-in should use its own default font.

Return Values

The method returns an HRESULT.

Remarks

This method enables a host to provide a standard font for use by any Silverlight-based applications that it hosts. Host applications that host specific Silverlight content will typically apply all fonts from within the hosted application. In this case, be sure to set bstrCompositeFont to null in this method.

IXcpControlHost3::GetDefaultThemeXaml

Provides the host-specific default styles and templates if available.

HRESULT DefaultThemeXaml(
  BSTR assemblyName,
  LPBSTR pbstrXaml
); 

Parameters

assemblyName

  [in]  String specifying the name of the assembly to load theme information for.

pbstrXaml

  [out, retval]  Pointer to a string containing XAML-based styles and templates or null if the hosted application should use its own default styles and templates.

Return Values

The method returns an HRESULT.

Remarks

This method enables a host to provide a standard theme for use by any Silverlight-based applications that it hosts. The XAML returned by this method will be used in place of the assembly's generic.xaml content.

Host applications that host specific Silverlight content will typically apply all styles from within the hosted application and set pbstrXaml to null in this method.

IXcpObject Interface

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

XcpHostOptions

XcpHostOptions is an enumeration specified by xcpctrl.idl and used by IXcpControlHost::GetHostOptions. Combined values of the enumeration specify runtime options that are applied against the hosted Silverlight plug-in when an instance is created.

Syntax

typedef enum XcpHostOptions{
  XcpHostOption_FreezeOnInitialFrame  =0x01,
  XcpHostOption_DisableFullScreen  =0x02,
  XcpHostOption_DisableManagedExecution  =0x08,
  XcpHostOption_EnableCrossDomainDownloads  =0x10
  XcpHostOption_UseCustomAppDomain  =0x020,
  XcpHostOption_DisableNetworking  =0x040,  
  XcpHostOption_DisableScriptCallouts  =0x080,
  XcpHostOption_EnableHtmlDomAccess  =0x100,
  XcpHostOption_EnableScriptableObjectAccess  =0x200,
// Added in Silverlight 4:
  XcpHostOption_EnableAssemblySharing  =0x800,
  XcpHostOption_HookGetComAutomationObject  = 0x1000,
  XcpHostOption_EnableElevatedPermissions  = 0x2000,
  XcpHostOption_EnableWindowlessAccessibility  = 0x4000,
  XcpHostOption_EnableUnbufferedDownloadStreams  =0x8000
};

Remarks

FreezeOnInitialFrame is for designer usage, to prevent startup animations from running.

DisableFullScreen is also for designer usage, or to generally disable full-screen display for Silverlight.

DisableManagedExecution is for special cases, mainly designer scenarios. No CLR runtime is loaded and no managed code is executed. This does not necessarily prevent XAML from parsing and XAML-based content from appearing, so long as managed calls were not part of the initialization sequence.

EnableCrossDomainDownloads relaxes some (but not all) cross-domain download restrictions.

UseCustomAppDomain informs Silverlight to not use the primary CLR AppDomain, and instead use the AppDomain specified in GetCustomAppDomain.

DisableNetworking shuts off the network stack entirely for Silverlight usage.

DisableScriptCallouts essentially disables event handling in script.

EnableHtmlDomAccess implies the same behavior as EnableHtmlAccess.

EnableScriptableObjectAccess enables/disables the ability to script to managed code via ScriptableTypeAttribute.

The following values were added to support features and scenarios for Silverlight 4.

EnableAssemblySharing causes the CLR to attempt to load assemblies as domain-neutral so that they can be shared across multiple plug-in instances. By default, each plug-in instance gets its own AppDomain into which its assemblies are loaded in manifest order. This option enables a performance gain for applications that host several plug-in instances.

NoteNote:

To enable assembly sharing, all IXcpControlHost implementations in the process must set this flag. If any hosts do not set this flag, the CLR will default to loading assemblies on a per-AppDomain basis. Note that correct functioning of this feature is only guaranteed when all hosts set this flag to the same value.

HookGetComAutomationObject enables the GetComAutomationObject method to intercept AutomationFactory.GetObject and CreateObject method calls from hosted applications.

EnableElevatedPermissions enables elevated trust features in properly configured hosted applications. For more information, see Trusted Applications.

EnableWindowlessAccessibility enables host applications to get host window handles for hosted Silverlight plug-ins in windowless mode. This is useful, for example, to enable user interface automation (UIA) with windowless mode.

EnableUnbufferedDownloadStreams is for designer usage to enable unbuffered video.

XcpHost_GetComAutomationObjectFlags

XcpHost_GetComAutomationObjectFlags is an enumeration specified by xcpctrl.idl and used by IXcpControlHost3::GetComAutomationObject to determine the nature of a request for an Automation object.

Syntax

typedef enum XcpHostOptions{
  XcpHost_GetComAutomationObjectFlag_Get  =0x01,
  XcpHost_GetComAutomationObjectFlag_Create  =0x02,
} XcpHost_GetComAutomationObjectFlags;

Remarks

GetComAutomationObjectFlag_Get indicates that the hosted application is calling the AutomationFactory.GetObject method.

GetComAutomationObjectFlag_Create indicates that the hosted application is calling the AutomationFactory.CreateObject method.

host.h COM Interfaces

The following interfaces are supported for Internet Explorer, Safari (Macintosh only), and Firefox. These interfaces are used for integrating the Silverlight content area into another control, typically with that other control also being a hosted control in an HTML page. You can get the interfaces through querying for the interface from the primary Silverlight plug-in. The definition for these interfaces can be found in the file host.h.

ISilverlightViewer

ISilverlightViewerProvider

IRenderTargetBitmap

XRECT

ISilverlightViewer Interface

Provides render target input and message handling for the Silverlight content area.

The ISilverlightViewer interface exposes the following methods.

CreateRenderTargetBitmap

ProcessInput

SuppressBrowserEvents

ISilverlightViewer::CreateRenderTargetBitmap

Provides the Silverlight content as a bitmap area.

Syntax

HRESULT CreateRenderTargetBitmap(
  uint32  uBackground,
  int32  nOffsetX,
  int32  nOffsetY,
  uint32  nWidth,
  uint32  nHeight,
  void*  pvBits,
  IRenderTargetBitmap  **ppIRenderTargetBitmap
);

Parameters

uBackground

  [in]  A premultiplied ARGB color value.

nOffsetX

  [in]  X-offset vs. content area in pixels.

nOffsetY,

  [in]  Y-offset vs. content area in pixels.

nWidth

  [in]  Width of content to render in pixels.

nHeight

  [in]  Height of content to render in pixels.

pvBits

  [in]  Pointer to a 32-bit ARGB color buffer.

ppIRenderTargetBitmap

  [out]  Destination render target bitmap interface.

Return Values

The method returns an HRESULT.

ISilverlightViewer::ProcessInput

Provides hooks so that input on the Silverlight content area can go to the host viewer.

Syntax

HRESULT ProcessInput(
  uint32  msg,
  uint32  wParam,
  uint32  lParam,
  void*  curEvent,
  int32  x,
  int32  y,
  uint32  *fHandled
);

Parameters

msg

  [in]  The message code.

wParam

  [in]  First param set for the message.

lParam

  [in]  Second param set for the message.

curEvent

  [in]  Pointer to input event.

x

  [in]  x-position of mouse input.

y

  [in]  y-position of mouse input.

fHandled

  [out]  Sends any desired code onward to the application (might parallel the HRESULT).

Return Values

The method returns an HRESULT.

Remarks

On the Macintosh, pass 0 for msg, wParam, lParam, and pass the event pointer for curEvent. On Windows, pass the message information for msg, wParam, lParam, and pass null for curEvent.

ISilverlightViewer::SuppressBrowserEvents

Instructs the Silverlight runtime to use only events that come through ProcessInput, and to not use events from the browser host.

Syntax

void SuppressBrowserEvents(
  INT32  bSuppress
);

Parameters

bSuppress

  [in]  Set this to a value other than zero to use only events that come through ProcessInput, and to not use events from the browser host.

Remarks

Calling this method has no effect for Silverlight plug-ins when the operating system is Microsoft Windows. This method is provided as a workaround for situations on other systems where the coordinates provided for mouse events from the browser host become invalid. This might happen if Silverlight enters full-screen mode. Hosts should call this method if the plug-in enters full-screen mode or the host reference frame for coordinate values changes relationship to the location of the Silverlight plug-in in some other way.

ISilverlightViewerProvider Interface

Provides a method to return an ISilverlightViewer interface.

In addition to IUnknown, ISilverlightViewerProvider exposes the following method.

GetSilverlightViewer

ISilverlightViewerProvider::GetSilverlightViewer

Gets a reference to an ISilverlightViewer interface. Call GetSilverlightViewer on the Silverlight plug-in object to get its ISilverlightViewer implementation.

Syntax

HRESULT GetSilverlightViewer(
  ISilverlightViewer**  ppSilverlightViewer
);

Parameters

ppSilverlightViewer

  [out]  Pointer to the returned interface. May be null if the control is not loaded.

Return Values

The method returns an HRESULT.

IRenderTargetBitmap Interface

Renders a bitmap that is used as a viewer input.

The IRenderTargetBitmap interface exposes the following method.

Render

IRenderTargetBitmap::Render

Renders the bitmap to a surface. Call this per your control's rendering behavior/loop, and map the XRECT values to your rendering system.

Syntax

HRESULT Render(
  void*  pElement,
  XRECT  *prcDirtyRect
);

Parameters

pElement

  [in]  Pointer to the element to render.

prcDirtyRect

  [out]  Rect region to render to.

Return Values

The method returns an HRESULT.

XRECT Structure

Supports the Render method.

struct XRECT
{
  int  X;
  int  Y;
  int  Width;
  int  Height;
}

See Also

Concepts