System.Web.UI.ClientScriptManager.GetCallbackEventReference Method

Obtains a reference to a client function that, when invoked, initiates a client call back to a server event. The client function for this overloaded method includes a specified control, argument, client script, and context.

Syntax

public string GetCallbackEventReference (Control control, string argument, string clientCallback, string context)

Parameters

control
The server System.Web.UI.Control that handles the client callback. The control must implement the System.Web.UI.ICallbackEventHandler interface and provide a ICallbackEventHandler.RaiseCallbackEvent(string) method.
argument
An argument passed from the client script to the server
clientCallback
The name of the client event handler that receives the result of the successful server event.
context
The client script that is evaluated on the client prior to initiating the callback. The result of the script is passed back to the client event handler.

Returns

The name of a client function that invokes the client callback.

Remarks

The ClientScriptManager.GetCallbackEventReference(Control, string, string, string) method performs an out-of-band callback to the server that is a modified version of a page's normal life cycle. For more information, see Client Callbacks Without Postbacks in ASP.NET Pages.

Note:

When the browser is Microsoft Internet Explorer (version 5.0 or later), the script callback mechanism is implemented through the Microsoft.XmlHttp COM object and requires the browser to be set to run ActiveX controls. For other browsers, an XMLHttpRequest using the browser's local Document Object Model (DOM) is used. To check whether a browser supports client callbacks, use the System.Web.Configuration.HttpCapabilitiesBase.SupportsCallback property. To check whether a browser supports XML over HTTP, use the System.Web.Configuration.HttpCapabilitiesBase.SupportsXmlHttp property. Both properties are accessible through the System.Web.HttpRequest.Browser property of the intrinsic ASP.NET System.Web.HttpContext.Request object.

The ClientScriptManager.GetCallbackEventReference(Control, string, string, string) overload of the erload:System.Web.UI.ClientScriptManager.GetCallbackEventReference method performs a callback synchronously using XML over HTTP. When sending data synchronously in a callback scenario, synchronous callbacks return immediately and do not block the browser. No two synchronous callbacks callback can execute at the same time in the browser. If a second synchronous callback is fired while one is currently pending, the second synchronous callback cancels the first and only the second callback will return.

To send data asynchronously, use one of the overloads that takes the useAsync parameter, which is a Boolean value controlling this behavior. In the asynchronous scenario you can have multiple pending callbacks; however, the order in which they return is not guaranteed to match the order in which they were initiated.

Additionally, this overload of the erload:System.Web.UI.ClientScriptManager.GetCallbackEventReference method specifies no client function to handle the case of an error condition generated by the ICallbackEventHandler.RaiseCallbackEvent(string) method. To specify a client error callback handler, use one of the overloads that takes the clientErrorCallback parameter.

The ClientScriptManager.GetCallbackEventReference(Control, string, string, string) method takes an optional string argument parameter and returns a string. To pass in or to receive multiple values, concatenate values in the input or return string, respectively.

Note:

Avoid using the view state in the implementation of page or control properties that need be updated during script callback operations. If the properties are to survive page requests, you can use session state.

Requirements

Namespace: System.Web.UI
Assembly: System.Web (in System.Web.dll)
Assembly Versions: 2.0.0.0
Since: .NET 2.0