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 ActiveX 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
IXcpObject Interface
IXcpControl Interface
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
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
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
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::get_Settings
Retrieves settings from the browser.
Syntax
HRESULT get_Settings(
IDispatch** pSettings
);
Parameters
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
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
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 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
IXcpControl2 Interface
IXcpControl2::LoadRuntime
Loads the CLR runtime.
Syntax
Parameters
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
Parameters
Return Values
The method returns an HRESULT.
IXcpControlHost2 Interface
Provides application domain support and other support that is relevant only for version 2 of the Silverlight control.
interface IXcpControlHost2 : IXcpControlHost
In addition to the methods inherited from IUnknown and IXcpControlHost , 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 input for GetHostOptions, 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 ActiveX control.
HRESULT GetControlVersion(
UINT *puMajorVersion,
UINT *puMinorVersion
);
Parameters
puMajorVersion
[out] The integer value for the major version number of the installed Silverlight ActiveX control.
puMinorVersion
[out] The integer value for the minor version number of the installed Silverlight ActiveX control.
Return Values
The method returns an HRESULT.
Remarks
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 control 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,
};
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.
Some values of this enumeration (for example UseCustomAppDomain) were added to support features and scenarios for version 2 of the Silverlight control.
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
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;
}