Export (0) Print
Expand All

Socket.SendPacketsAsync Method

Sends a collection of files or in memory data buffers asynchronously to a connected Socket object.

Namespace:  System.Net.Sockets
Assembly:  System (in System.dll)

public bool SendPacketsAsync(
	SocketAsyncEventArgs e
)

Parameters

e
Type: System.Net.Sockets.SocketAsyncEventArgs

The System.Net.Sockets.SocketAsyncEventArgs object to use for this asynchronous socket operation.

Return Value

Type: System.Boolean
Returns true if the I/O operation is pending. The SocketAsyncEventArgs.Completed event on the e parameter will be raised upon completion of the operation.
Returns false if the I/O operation completed synchronously. In this case, The SocketAsyncEventArgs.Completed event on the e parameter will not be raised and the e object passed as a parameter may be examined immediately after the method call returns to retrieve the result of the operation.

ExceptionCondition
FileNotFoundException

The file specified in the SendPacketsElement.FilePath property was not found.

InvalidOperationException

A socket operation was already in progress using the System.Net.Sockets.SocketAsyncEventArgs object specified in the e parameter.

NotSupportedException

Windows XP or later is required for this method. This exception also occurs if the Socket is not connected to a remote host.

ObjectDisposedException

The Socket has been closed.

SocketException

A connectionless Socket is being used and the file being sent exceeds the maximum packet size of the underlying transport.

The SendPacketsAsync method is used to send a collection of files or in memory data buffers to remote host. The Socket must already be connected to the remote host.

If a System.Net.Sockets.SendPacketsElement references a file in the working directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards and UNC share names are supported. If the file is not found, FileNotFoundException is thrown.

To be notified of completion, you must create a callback method that implements the EventHandler<SocketAsyncEventArgs> delegate and attach the callback to the SocketAsyncEventArgs.Completed event.

The SocketAsyncEventArgs.SendPacketsFlags property on the e parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see TransmitFileOptions.

The following properties and events on the System.Net.Sockets.SocketAsyncEventArgs object are required to successfully call this method:

The caller may set the SocketAsyncEventArgs.UserToken property to any user state object desired before calling the SendPacketsAsync method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members.

This method uses the TransmitPackets function found in the Windows Sockets 2 API. For more information about the TransmitPackets function and its flags, see the Windows Sockets documentation in the MSDN Library.

Although intended for connection-oriented protocols, the SendPacketsAsync method also works for connectionless protocols, provided that you first call the BeginConnect, Connect, or ConnectAsync method to establish a default remote host. With connectionless protocols, you must also be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and SendPacketsAsync throws a SocketException exception.

The SendPacketsAsync method is optimized according to the operating system on which it is used. On Windows server editions, the SendPacketsAsync method is optimized for high performance.

On Windows client editions, the SendPacketsAsync method is optimized for minimum memory and resource utilization.

Use of the TransmitFileOptions.UseKernelApc flag in the SocketAsyncEventArgs.SendPacketsFlags property on the e parameter can deliver significant performance benefits. If the thread initiating the SendPacketsAsync method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state

.NET Framework

Supported in: 4.5, 4, 3.5 SP1, 3.0 SP1, 2.0 SP1

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft