ClientScriptManager.GetCallbackEventReference Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Obtains a reference to a client function that, when invoked, initiates a client call back to a server event.
Overloads
| GetCallbackEventReference(Control, String, String, String) |
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. |
| GetCallbackEventReference(Control, String, String, String, Boolean) |
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified control, argument, client script, context, and Boolean value. |
| GetCallbackEventReference(String, String, String, String, String, Boolean) |
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified target, argument, client script, context, error handler, and Boolean value. |
| GetCallbackEventReference(Control, String, String, String, String, Boolean) |
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified control, argument, client script, context, error handler, and Boolean value. |
GetCallbackEventReference(Control, String, String, String)
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.
public:
System::String ^ GetCallbackEventReference(System::Web::UI::Control ^ control, System::String ^ argument, System::String ^ clientCallback, System::String ^ context);public string GetCallbackEventReference (System.Web.UI.Control control, string argument, string clientCallback, string context);member this.GetCallbackEventReference : System.Web.UI.Control * string * string * string -> stringPublic Function GetCallbackEventReference (control As Control, argument As String, clientCallback As String, context As String) As StringParameters
- control
- Control
The server Control that handles the client callback. The control must implement the ICallbackEventHandler interface and provide a RaiseCallbackEvent(String) method.
- argument
- String
An argument passed from the client script to the server
RaiseCallbackEvent(String) method.
- clientCallback
- String
The name of the client event handler that receives the result of the successful server event.
- context
- String
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.
Exceptions
The Control specified is null.
The Control specified does not implement the ICallbackEventHandler interface.
Examples
The following code example demonstrates how to use two overloads of the GetCallbackEventReference method in a client callback scenario that increments integers.
Two callback mechanisms are shown; the difference between them is the use of the context parameter. A ReceiveServerData1 client callback function is provided using the context parameter. In contrast, the ReceiveServerData2 client callback function is defined in a <script> block on the page. A RaiseCallbackEvent method is the server handler that increments the value that is passed to it and the GetCallbackResult method returns the incremented value as a string. If the RaiseCallbackEvent method returns an error, then the ProcessCallBackError client function is called.
<%@ Page Language="C#" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
public int cbCount = 0;
// Define method that processes the callbacks on server.
public void RaiseCallbackEvent(String eventArgument)
{
cbCount = Convert.ToInt32(eventArgument) + 1;
}
// Define method that returns callback result.
public string GetCallbackResult()
{
return cbCount.ToString();
}
protected void Page_Load(object sender, EventArgs e)
{
// Define a StringBuilder to hold messages to output.
StringBuilder sb = new StringBuilder();
// Check if this is a postback.
sb.Append("No page postbacks have occurred.");
if (Page.IsPostBack)
{
sb.Append("A page postback has occurred.");
}
// Write out any messages.
MyLabel.Text = sb.ToString();
// Get a ClientScriptManager reference from the Page class.
ClientScriptManager cs = Page.ClientScript;
// Define one of the callback script's context.
// The callback script will be defined in a script block on the page.
StringBuilder context1 = new StringBuilder();
context1.Append("function ReceiveServerData1(arg, context)");
context1.Append("{");
context1.Append("Message1.innerText = arg;");
context1.Append("value1 = arg;");
context1.Append("}");
// Define callback references.
String cbReference1 = cs.GetCallbackEventReference(this, "arg",
"ReceiveServerData1", context1.ToString());
String cbReference2 = cs.GetCallbackEventReference("'" +
Page.UniqueID + "'", "arg", "ReceiveServerData2", "",
"ProcessCallBackError", false);
String callbackScript1 = "function CallTheServer1(arg, context) {" +
cbReference1 + "; }";
String callbackScript2 = "function CallTheServer2(arg, context) {" +
cbReference2 + "; }";
// Register script blocks will perform call to the server.
cs.RegisterClientScriptBlock(this.GetType(), "CallTheServer1",
callbackScript1, true);
cs.RegisterClientScriptBlock(this.GetType(), "CallTheServer2",
callbackScript2, true);
}
</script>
<script type="text/javascript">
var value1 = 0;
var value2 = 0;
function ReceiveServerData2(arg, context)
{
Message2.innerText = arg;
value2 = arg;
}
function ProcessCallBackError(arg, context)
{
Message2.innerText = 'An error has occurred.';
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>ClientScriptManager Example</title>
</head>
<body>
<form id="Form1"
runat="server">
<div>
Callback 1 result: <span id="Message1">0</span>
<br />
Callback 2 result: <span id="Message2">0</span>
<br /> <br />
<input type="button"
value="ClientCallBack1"
onclick="CallTheServer1(value1, alert('Increment value'))"/>
<input type="button"
value="ClientCallBack2"
onclick="CallTheServer2(value2, alert('Increment value'))"/>
<br /> <br />
<asp:Label id="MyLabel"
runat="server"></asp:Label>
</div>
</form>
</body>
</html>
<%@ Page Language="VB" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
Public cbCount As Integer = 0
' Define method that processes the callbacks on server.
Public Sub RaiseCallbackEvent(ByVal eventArgument As String) _
Implements System.Web.UI.ICallbackEventHandler.RaiseCallbackEvent
cbCount = Convert.ToInt32(eventArgument) + 1
End Sub
' Define method that returns callback result.
Public Function GetCallbackResult() _
As String Implements _
System.Web.UI.ICallbackEventHandler.GetCallbackResult
Return cbCount.ToString()
End Function
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
' Define a StringBuilder to hold messages to output.
Dim sb As New StringBuilder()
' Check if this is a postback.
sb.Append("No page postbacks have occurred.")
If (Page.IsPostBack) Then
sb.Append("A page postback has occurred.")
End If
' Write out any messages.
MyLabel.Text = sb.ToString()
' Get a ClientScriptManager reference from the Page class.
Dim cs As ClientScriptManager = Page.ClientScript
' Define one of the callback script's context.
' The callback script will be defined in a script block on the page.
Dim context1 As New StringBuilder()
context1.Append("function ReceiveServerData1(arg, context)")
context1.Append("{")
context1.Append("Message1.innerText = arg;")
context1.Append("value1 = arg;")
context1.Append("}")
' Define callback references.
Dim cbReference1 As String = cs.GetCallbackEventReference(Me, "arg", _
"ReceiveServerData1", context1.ToString())
Dim cbReference2 As String = cs.GetCallbackEventReference("'" & _
Page.UniqueID & "'", "arg", "ReceiveServerData2", "", "ProcessCallBackError", False)
Dim callbackScript1 As String = "function CallTheServer1(arg, context) {" + _
cbReference1 + "; }"
Dim callbackScript2 As String = "function CallTheServer2(arg, context) {" + _
cbReference2 + "; }"
' Register script blocks will perform call to the server.
cs.RegisterClientScriptBlock(Me.GetType(), "CallTheServer1", _
callbackScript1, True)
cs.RegisterClientScriptBlock(Me.GetType(), "CallTheServer2", _
callbackScript2, True)
End Sub
</script>
<script type="text/javascript">
var value1 = 0;
var value2 = 0;
function ReceiveServerData2(arg, context)
{
Message2.innerText = arg;
value2 = arg;
}
function ProcessCallBackError(arg, context)
{
Message2.innerText = 'An error has occurred.';
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>ClientScriptManager Example</title>
</head>
<body>
<form id="Form1"
runat="server">
<div>
Callback 1 result: <span id="Message1">0</span>
<br />
Callback 2 result: <span id="Message2">0</span>
<br /> <br />
<input type="button"
value="ClientCallBack1"
onclick="CallTheServer1(value1, alert('Increment value'))"/>
<input type="button"
value="ClientCallBack2"
onclick="CallTheServer2(value2, alert('Increment value'))"/>
<br /> <br />
<asp:Label id="MyLabel"
runat="server"></asp:Label>
</div>
</form>
</body>
</html>
Remarks
The 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 Implementing Client Callbacks Without Postbacks.
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 SupportsCallback property. To check whether a browser supports XML over HTTP, use the SupportsXmlHttp property. Both properties are accessible through the Browser property of the intrinsic ASP.NET Request object.
The GetCallbackEventReference overload of the 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 GetCallbackEventReference method specifies no client function to handle the case of an error condition generated by the RaiseCallbackEvent method. To specify a client error callback handler, use one of the overloads that takes the clientErrorCallback parameter.
The 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.
See also
Applies to
GetCallbackEventReference(Control, String, String, String, Boolean)
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified control, argument, client script, context, and Boolean value.
public:
System::String ^ GetCallbackEventReference(System::Web::UI::Control ^ control, System::String ^ argument, System::String ^ clientCallback, System::String ^ context, bool useAsync);public string GetCallbackEventReference (System.Web.UI.Control control, string argument, string clientCallback, string context, bool useAsync);member this.GetCallbackEventReference : System.Web.UI.Control * string * string * string * bool -> stringPublic Function GetCallbackEventReference (control As Control, argument As String, clientCallback As String, context As String, useAsync As Boolean) As StringParameters
- control
- Control
The server Control that handles the client callback. The control must implement the ICallbackEventHandler interface and provide a RaiseCallbackEvent(String) method.
- argument
- String
An argument passed from the client script to the server
RaiseCallbackEvent(String) method.
- clientCallback
- String
The name of the client event handler that receives the result of the successful server event.
- context
- String
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.
- useAsync
- Boolean
true to perform the callback asynchronously; false to perform the callback synchronously.
Returns
The name of a client function that invokes the client callback.
Exceptions
The Control specified is null.
The Control specified does not implement the ICallbackEventHandler interface.
Remarks
This overload of the GetCallbackEventReference method requires a useAsync parameter, which allows you to perform the client callback asynchronously by setting the value to true. The overload versions of this method that do not require the useAsync parameter set the value to false by default.
For more information on this method, see the remarks for the overload GetCallbackEventReference method.
See also
Applies to
GetCallbackEventReference(String, String, String, String, String, Boolean)
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified target, argument, client script, context, error handler, and Boolean value.
public:
System::String ^ GetCallbackEventReference(System::String ^ target, System::String ^ argument, System::String ^ clientCallback, System::String ^ context, System::String ^ clientErrorCallback, bool useAsync);public string GetCallbackEventReference (string target, string argument, string clientCallback, string context, string clientErrorCallback, bool useAsync);member this.GetCallbackEventReference : string * string * string * string * string * bool -> stringPublic Function GetCallbackEventReference (target As String, argument As String, clientCallback As String, context As String, clientErrorCallback As String, useAsync As Boolean) As StringParameters
- target
- String
The name of a server Control that handles the client callback. The control must implement the ICallbackEventHandler interface and provide a RaiseCallbackEvent(String) method.
- argument
- String
An argument passed from the client script to the server
RaiseCallbackEvent(String) method.
- clientCallback
- String
The name of the client event handler that receives the result of the successful server event.
- context
- String
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.
- clientErrorCallback
- String
The name of the client event handler that receives the result when an error occurs in the server event handler.
- useAsync
- Boolean
true to perform the callback asynchronously; false to perform the callback synchronously.
Returns
The name of a client function that invokes the client callback.
Examples
The following code example demonstrates how to use two overloads of the GetCallbackEventReference method in a client callback scenario that increments integers.
Two callback mechanisms are shown; the difference between them is the use of the context parameter. A ReceiveServerData1 client callback function is provided using the context parameter. In contrast, the ReceiveServerData2 client callback function is defined in a <script> block on the page. A RaiseCallbackEvent method is the server handler that increments the value that is passed to it and the GetCallbackResult method returns the incremented value as a string. If the RaiseCallbackEvent method returns an error, then the client function ProcessCallBackError is called.
<%@ Page Language="C#" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
public int cbCount = 0;
// Define method that processes the callbacks on server.
public void RaiseCallbackEvent(String eventArgument)
{
cbCount = Convert.ToInt32(eventArgument) + 1;
}
// Define method that returns callback result.
public string GetCallbackResult()
{
return cbCount.ToString();
}
protected void Page_Load(object sender, EventArgs e)
{
// Define a StringBuilder to hold messages to output.
StringBuilder sb = new StringBuilder();
// Check if this is a postback.
sb.Append("No page postbacks have occurred.");
if (Page.IsPostBack)
{
sb.Append("A page postback has occurred.");
}
// Write out any messages.
MyLabel.Text = sb.ToString();
// Get a ClientScriptManager reference from the Page class.
ClientScriptManager cs = Page.ClientScript;
// Define one of the callback script's context.
// The callback script will be defined in a script block on the page.
StringBuilder context1 = new StringBuilder();
context1.Append("function ReceiveServerData1(arg, context)");
context1.Append("{");
context1.Append("Message1.innerText = arg;");
context1.Append("value1 = arg;");
context1.Append("}");
// Define callback references.
String cbReference1 = cs.GetCallbackEventReference(this, "arg",
"ReceiveServerData1", context1.ToString());
String cbReference2 = cs.GetCallbackEventReference("'" +
Page.UniqueID + "'", "arg", "ReceiveServerData2", "",
"ProcessCallBackError", false);
String callbackScript1 = "function CallTheServer1(arg, context) {" +
cbReference1 + "; }";
String callbackScript2 = "function CallTheServer2(arg, context) {" +
cbReference2 + "; }";
// Register script blocks will perform call to the server.
cs.RegisterClientScriptBlock(this.GetType(), "CallTheServer1",
callbackScript1, true);
cs.RegisterClientScriptBlock(this.GetType(), "CallTheServer2",
callbackScript2, true);
}
</script>
<script type="text/javascript">
var value1 = 0;
var value2 = 0;
function ReceiveServerData2(arg, context)
{
Message2.innerText = arg;
value2 = arg;
}
function ProcessCallBackError(arg, context)
{
Message2.innerText = 'An error has occurred.';
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>ClientScriptManager Example</title>
</head>
<body>
<form id="Form1"
runat="server">
<div>
Callback 1 result: <span id="Message1">0</span>
<br />
Callback 2 result: <span id="Message2">0</span>
<br /> <br />
<input type="button"
value="ClientCallBack1"
onclick="CallTheServer1(value1, alert('Increment value'))"/>
<input type="button"
value="ClientCallBack2"
onclick="CallTheServer2(value2, alert('Increment value'))"/>
<br /> <br />
<asp:Label id="MyLabel"
runat="server"></asp:Label>
</div>
</form>
</body>
</html>
<%@ Page Language="VB" %>
<%@ Implements Interface="System.Web.UI.ICallbackEventHandler" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
Public cbCount As Integer = 0
' Define method that processes the callbacks on server.
Public Sub RaiseCallbackEvent(ByVal eventArgument As String) _
Implements System.Web.UI.ICallbackEventHandler.RaiseCallbackEvent
cbCount = Convert.ToInt32(eventArgument) + 1
End Sub
' Define method that returns callback result.
Public Function GetCallbackResult() _
As String Implements _
System.Web.UI.ICallbackEventHandler.GetCallbackResult
Return cbCount.ToString()
End Function
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
' Define a StringBuilder to hold messages to output.
Dim sb As New StringBuilder()
' Check if this is a postback.
sb.Append("No page postbacks have occurred.")
If (Page.IsPostBack) Then
sb.Append("A page postback has occurred.")
End If
' Write out any messages.
MyLabel.Text = sb.ToString()
' Get a ClientScriptManager reference from the Page class.
Dim cs As ClientScriptManager = Page.ClientScript
' Define one of the callback script's context.
' The callback script will be defined in a script block on the page.
Dim context1 As New StringBuilder()
context1.Append("function ReceiveServerData1(arg, context)")
context1.Append("{")
context1.Append("Message1.innerText = arg;")
context1.Append("value1 = arg;")
context1.Append("}")
' Define callback references.
Dim cbReference1 As String = cs.GetCallbackEventReference(Me, "arg", _
"ReceiveServerData1", context1.ToString())
Dim cbReference2 As String = cs.GetCallbackEventReference("'" & _
Page.UniqueID & "'", "arg", "ReceiveServerData2", "", "ProcessCallBackError", False)
Dim callbackScript1 As String = "function CallTheServer1(arg, context) {" + _
cbReference1 + "; }"
Dim callbackScript2 As String = "function CallTheServer2(arg, context) {" + _
cbReference2 + "; }"
' Register script blocks will perform call to the server.
cs.RegisterClientScriptBlock(Me.GetType(), "CallTheServer1", _
callbackScript1, True)
cs.RegisterClientScriptBlock(Me.GetType(), "CallTheServer2", _
callbackScript2, True)
End Sub
</script>
<script type="text/javascript">
var value1 = 0;
var value2 = 0;
function ReceiveServerData2(arg, context)
{
Message2.innerText = arg;
value2 = arg;
}
function ProcessCallBackError(arg, context)
{
Message2.innerText = 'An error has occurred.';
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>ClientScriptManager Example</title>
</head>
<body>
<form id="Form1"
runat="server">
<div>
Callback 1 result: <span id="Message1">0</span>
<br />
Callback 2 result: <span id="Message2">0</span>
<br /> <br />
<input type="button"
value="ClientCallBack1"
onclick="CallTheServer1(value1, alert('Increment value'))"/>
<input type="button"
value="ClientCallBack2"
onclick="CallTheServer2(value2, alert('Increment value'))"/>
<br /> <br />
<asp:Label id="MyLabel"
runat="server"></asp:Label>
</div>
</form>
</body>
</html>
Remarks
This overload of the GetCallbackEventReference method takes a target string parameter instead of a Control parameter. Use this overload when you want the callback to go back to something other than a string containing the UniqueID of the control.
Additionally, this overload of the GetCallbackEventReference method requires a useAsync and a clientErrorCallback parameter. The useAsync parameter allows you to perform the client callback asynchronously by setting the value to true. The overload versions of this method that do not require the useAsync parameter set the value to false by default. The clientErrorCallback parameter allows you to define the name of the client function that is called if the server handler, the RaiseCallbackEvent method, returns an error. The overload versions of this method that do not require the clientErrorCallback parameter set the value to null.
For more information on this method, see the remarks for the overload GetCallbackEventReference method.
See also
Applies to
GetCallbackEventReference(Control, String, String, String, String, Boolean)
Obtains a reference to a client function that, when invoked, initiates a client call back to server events. The client function for this overloaded method includes a specified control, argument, client script, context, error handler, and Boolean value.
public:
System::String ^ GetCallbackEventReference(System::Web::UI::Control ^ control, System::String ^ argument, System::String ^ clientCallback, System::String ^ context, System::String ^ clientErrorCallback, bool useAsync);public string GetCallbackEventReference (System.Web.UI.Control control, string argument, string clientCallback, string context, string clientErrorCallback, bool useAsync);member this.GetCallbackEventReference : System.Web.UI.Control * string * string * string * string * bool -> stringPublic Function GetCallbackEventReference (control As Control, argument As String, clientCallback As String, context As String, clientErrorCallback As String, useAsync As Boolean) As StringParameters
- control
- Control
The server Control that handles the client callback. The control must implement the ICallbackEventHandler interface and provide a RaiseCallbackEvent(String) method.
- argument
- String
An argument passed from the client script to the server RaiseCallbackEvent(String) method.
- clientCallback
- String
The name of the client event handler that receives the result of the successful server event.
- context
- String
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.
- clientErrorCallback
- String
The name of the client event handler that receives the result when an error occurs in the server event handler.
- useAsync
- Boolean
true to perform the callback asynchronously; false to perform the callback synchronously.
Returns
The name of a client function that invokes the client callback.
Exceptions
The Control specified is null.
The Control specified does not implement the ICallbackEventHandler interface.
Remarks
This overload of the GetCallbackEventReference method requires a useAsync and a clientErrorCallback parameter. The useAsync parameter allows you to perform the client callback asynchronously by setting the value to true. The overload versions of this method that do not require the useAsync parameter set the value to false by default. The clientErrorCallback parameter allows you to define the name of the client function that is called if the server handler (the RaiseCallbackEvent method) returns an error. The overload versions of this method that do not require the clientErrorCallback parameter set the value to null.
For more information on this method, see the remarks for the overload GetCallbackEventReference method.
