Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Socket.BeginSend Method

Sends data asynchronously to a connected Socket.

[Visual Basic]
Public Function BeginSend( _
   ByVal buffer() As Byte, _
   ByVal offset As Integer, _
   ByVal size As Integer, _
   ByVal socketFlags As SocketFlags, _
   ByVal callback As AsyncCallback, _
   ByVal state As Object _
) As IAsyncResult
[C#]
public IAsyncResult BeginSend(
 byte[] buffer,
 int offset,
 int size,
 SocketFlags socketFlags,
 AsyncCallback callback,
 object state
);
[C++]
public: IAsyncResult* BeginSend(
 unsigned char buffer __gc[],
 int offset,
 int size,
 SocketFlags socketFlags,
 AsyncCallback* callback,
 Object* state
);
[JScript]
public function BeginSend(
   buffer : Byte[],
 offset : int,
 size : int,
 socketFlags : SocketFlags,
 callback : AsyncCallback,
 state : Object
) : IAsyncResult;

Parameters

buffer
An array of type Byte that contains the data to send.
offset
The zero-based position in the buffer parameter at which to begin sending data.
size
The number of bytes to send.
socketFlags
A bitwise combination of the SocketFlags values.
callback
The AsyncCallback delegate.
state
An object containing state information for this request.

Return Value

An IAsyncResult that references the asynchronous send.

Exceptions

Exception Type Condition
ArgumentNullException buffer is a null reference (Nothing in Visual Basic).
SocketException An error occurred when attempting to access the socket. See remarks section below.
ArgumentOutOfRangeException offset is less than 0.

-or-

offset is less than the length of buffer.

-or-

size is less than 0.

-or-

size is greater than the length of buffer minus the value of the offset parameter.

ObjectDisposedException The Socket has been closed.

Remarks

The BeginSend method starts an asynchronous send operation to the remote host established in the Connect, BeginConnect, Accept, BeginAccept method. BeginSend will throw an exception if you do not first call Accept, BeginAccept, Connect, or BeginConnect. Calling the BeginSend method gives you the ability to send data within a separate execution thread.

You can create acallback method that implements the AsyncCallback delegate and pass its name to the BeginSend method. To do this, at the very minimum, your state parameter must contain the connected or default Socket being used for communication. If your callback needs more information, you can create a small class or structure to hold the Socket and the other required information. Pass an instance of this class to the BeginSend method through the state parameter.

Your callback method should implement the EndSend method. When your application calls BeginSend, the system will use a separate thread to execute the specified callback method, and will block on EndSend until the Socket sends the number of bytes requested or throws an exception. If you want the original thread to block after you call the BeginSend method, use the WaitHandle.WaitOne method. Call Set in the callback method when you want the original thread to continue executing. For additional information on writing callback methods see Callback Sample.

Although intended for connection-oriented protocols, BeginSend also works for connectionless protocols, provided that you first call the Connect or BeginConnect method to establish a default remote host. If you are using a connectionless protocol and plan to send data to several different hosts, you should use BeginSendTo. It is okay to use BeginSendTo even after you have established a default remote host with Connect. You can also change the default remote host prior to calling BeginSend by making another call to Connect or BeginConnect. With connectionless protocols, you must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and BeginSend will throw a SocketException.

If you specify the DontRoute flag as the socketflags parameter, the data you are sending will not be routed. If you specify the OutOfBand flag as the socketflags parameter, only out-of-band (OOB) data is sent.

Note   If you receive a SocketException, use SocketException.ErrorCode to obtain the specific error code. Once you have obtained this code, you can refer to the Windows Socket Version 2 API error code documentation in MSDN for a detailed description of the error.

Example

[Visual Basic, C#, C++] The following example begins asynchronously sending data to a remote host.

[Visual Basic] 
allDone.Set()
Dim s As Socket = CType(ar.AsyncState, Socket)
s.EndConnect(ar)
Dim so2 As New StateObject()
so2.workSocket = s
Dim buff As Byte() = Encoding.ASCII.GetBytes("This is a test")
s.BeginSend(buff, 0, buff.Length, 0, New AsyncCallback(AddressOf Async_Send_Receive.Send_Callback), so2)
   End Sub 'Connect_Callback
   

[C#] 
allDone.Set();
Socket s = (Socket) ar.AsyncState;
s.EndConnect(ar);
StateObject so2 = new StateObject();
so2.workSocket = s;
byte[] buff = Encoding.ASCII.GetBytes("This is a test");
s.BeginSend(buff, 0, buff.Length,0,
                      new AsyncCallback(Async_Send_Receive.Send_Callback), so2);    

[C++] 
allDone->Set();
Socket* s = __try_cast<Socket*>(ar->AsyncState);
s->EndConnect(ar);
StateObject* so2 = new StateObject();
so2->workSocket = s;
Byte buff[] = Encoding::ASCII->GetBytes(S"This is a test");
s->BeginSend(buff, 0, buff->Length, SocketFlags::None,
    new AsyncCallback(0, &Async_Send_Receive::Send_Callback), so2);    

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework, Common Language Infrastructure (CLI) Standard

See Also

Socket Class | Socket Members | System.Net.Sockets Namespace | Including Asynchronous Calls | Callback Sample | Connect | AsyncCallback | EndSend

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft