DatagramSocket.GetOutputStreamAsync 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.
Overloads
| GetOutputStreamAsync(EndpointPair) |
Starts an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object that can then be used to send network data. |
| GetOutputStreamAsync(HostName, String) |
Starts an operation to get an IOutputStream to a remote destination specified by a remote hostname and a remote service name that can then be used to send network data. |
GetOutputStreamAsync(EndpointPair)
Starts an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object that can then be used to send network data.
public:
virtual IAsyncOperation<IOutputStream ^> ^ GetOutputStreamAsync(EndpointPair ^ endpointPair) = GetOutputStreamAsync;/// [Windows.Foundation.Metadata.Overload("GetOutputStreamWithEndpointPairAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair const& endpointPair);[Windows.Foundation.Metadata.Overload("GetOutputStreamWithEndpointPairAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<IOutputStream> GetOutputStreamAsync(EndpointPair endpointPair);function getOutputStreamAsync(endpointPair)Public Function GetOutputStreamAsync (endpointPair As EndpointPair) As IAsyncOperation(Of IOutputStream)Parameters
- endpointPair
- EndpointPair
An endpoint pair that represents the local hostname or local IP address, the local service name or local UDP port, the remote hostname or remote IP address, and the remote service name or remote UDP port.
Returns
An IOutputStream that represents the asynchronous operation.
- Attributes
Windows requirements
| App capabilities |
ID_CAP_NETWORKING [Windows Phone]
|
Remarks
The GetOutputStreamAsync(EndpointPair) method on a DatagramSocket is used to start an operation to get an IOutputStream to a remote network destination specified by an EndpointPair object. The IOutputStream can then be used to send data to the remote destination.
The GetOutputStreamAsync(EndpointPair) method will return an IOutputStream when it completes successfully. Writing to that stream will send datagrams to the remote host and service name specified. The IOutputStream will always send to the remote hostname and remote service name specified in the ConnectAsync method.
The RemoteHostName property of the EndpointPair passed in the endpointPair parameter can contain either the hostname or IP address of the remote destination. The RemoteServiceName property of the EndpointPair passed in the endpointPair parameter can contain either the service name or a UDP port of the remote destination. If the RemoteHostName property contains a hostname, then the GetOutputStreamAsync(EndpointPair) method results in name resolution of the remote hostname. If the RemoteServiceName property contains a service name, then the GetOutputStreamAsync method results in resolution of the remote service name to a UDP port.
The RemoteHostName and RemoteServiceName properties must be provided on the EndpointPair object passed in the endpointPair parameter. If the RemoteHostName is null or the RemoteServiceName is null or an empty string, an error will occur.
If the EndpointPair object passed in the endpointPair parameter contains a null LocalHostName property, then the system will supply the local IP address that will be used. If the EndpointPair object passed in the endpointPair parameter contains an empty string for the LocalServiceName property, then the system will supply the local UDP port that will be used.
There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:
- Use one of the GetOutputStreamAsync methods.
- After a successful call to one of the ConnectAsync methods, pass the OutputStream property to a DataWriter object and use methods on the DataWriter object to send data.
The GetOutputStreamAsync methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the GetOutputStreamAsync(EndpointPair) method is called, the app can set different values for the RemoteHostName and RemoteServiceName members in the endpointPair parameter.
To receive data from any remote endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call either BindEndpointAsync or BindServiceNameAsync method to bind the DatagramSocket to a local service name or UDP port before calling the GetOutputStreamAsync method. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.
The typical order of operations is as follows:
- Create the DatagramSocket.
- Use the Control property to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
- Assign the MessageReceived event to an event handler.
- Call the GetOutputStreamAsync(EndpointPair) method to get the OutputStream to send data to the remote endpoint. The GetOutputStreamAsync(EndpointPair) method will also bind the DatagramSocket to a local service name or UDP port and a local hostname or IP address using the endpointPair parameter.
- The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives. The GetOutputStreamAsync methods also differ from the ConnectAsync methods when an app uses the BindEndpointAsync or BindServiceNameAsync method to bind a local service name or UDP port. With the GetOutputStreamAsync methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync methods.
The BindServiceNameAsync(String, NetworkAdapter) method can be used to specify a network adapter before calling the GetOutputStreamAsync(EndpointPair) method. The specified adapter is used for the bind operation. If after calling BindServiceNameAsync(String, NetworkAdapter) and the endpointPair parameter passed to GetOutputStreamAsync(EndpointPair) specifies a LocalHostName, the GetOutputStreamAsync(EndpointPair) method will fail.
See also
Applies to
GetOutputStreamAsync(HostName, String)
Starts an operation to get an IOutputStream to a remote destination specified by a remote hostname and a remote service name that can then be used to send network data.
public:
virtual IAsyncOperation<IOutputStream ^> ^ GetOutputStreamAsync(HostName ^ remoteHostName, Platform::String ^ remoteServiceName) = GetOutputStreamAsync;/// [Windows.Foundation.Metadata.Overload("GetOutputStreamAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<IOutputStream> GetOutputStreamAsync(HostName const& remoteHostName, winrt::hstring const& remoteServiceName);[Windows.Foundation.Metadata.Overload("GetOutputStreamAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<IOutputStream> GetOutputStreamAsync(HostName remoteHostName, string remoteServiceName);function getOutputStreamAsync(remoteHostName, remoteServiceName)Public Function GetOutputStreamAsync (remoteHostName As HostName, remoteServiceName As String) As IAsyncOperation(Of IOutputStream)Parameters
- remoteHostName
- HostName
The remote hostname or remote IP address.
- remoteServiceName
-
String
Platform::String
winrt::hstring
The remote service name or remote UDP port.
Returns
An IOutputStream that representing the asynchronous operation.
- Attributes
Windows requirements
| App capabilities |
ID_CAP_NETWORKING [Windows Phone]
|
Remarks
The [GetOutputStreamAsync(HostName, String) method on a DatagramSocket is used to start an operation to get an IOutputStream to a remote network destination specified by a remote hostname and a remote service name. The IOutputStream can then be used to send data to the remote destination.
The [GetOutputStreamAsync(HostName, String) method will return an IOutputStream when it completes successfully. Writing to that stream will send datagrams to the remote host and service name specified. The IOutputStream will always send to the remote hostname and remote service name specified in the ConnectAsync method.
The remoteHostName parameter can contain either the hostname or IP address of the remote destination. The remoteServiceName parameter can contain either the service name or a UDP port of the remote destination. If the remoteHostName parameter contains a hostname, then the [GetOutputStreamAsync(HostName, String) method results in name resolution of the remote hostname. If the remoteServiceName parameter contains a service name, then the [GetOutputStreamAsync(HostName, String) method results in resolution of the remote service name to a UDP port.
The remoteHostName and remoteServiceName parameters must be provided. If the remoteHostName parameter is null or the remoteServiceName parameter is null or an empty string, an error will occur.
There are two ways of using a DatagramSocket to send UDP datagrams to a remote network destination:
- Use one of the GetOutputStreamAsync methods.
- After a successful call to one of the ConnectAsync methods, pass the OutputStream property to a DataWriter object and use methods on the DataWriter object to send data.
The GetOutputStreamAsync methods allow an app to send UDP datagrams using a DatagramSocket object to multiple network destinations. Each time the [GetOutputStreamAsync(HostName, String) method is called, the app can set different values for the remoteHostName and remoteServiceName parameters.
The ConnectAsync methods allow an app to send UDP datagrams using a DatagramSocket object to a single network destination.
To receive data from any remote endpoint on the DatagramSocket object, an app must assign the MessageReceived event to an event handler and then call either BindEndpointAsync or BindServiceNameAsync method to bind the DatagramSocket to a local service name or UDP port before calling the GetOutputStreamAsync method. The MessageReceived event handler must be set before any bind or connect operation, otherwise an error will occur.
The typical order of operations is as follows:
- Create the DatagramSocket.
- Use the Control property to retrieve a DatagramSocketControl object and set any advanced controls. This step is not normally needed by most apps.
- Assign the MessageReceived event to an event handler.
- Bind the DatagramSocket to a local service name or UDP port.
- The MessageReceived event handler will be invoked whenever a message from the remote endpoint arrives.
- Call the GetOutputStreamAsync method to get the OutputStream to send data to the remote endpoint. You can use the information contained in the DatagramSocketMessageReceivedEventArgs from the MessageReceived event handler to establish an OutputStream with the remote endpoint that authored a specific incoming message. The GetOutputStreamAsync methods also differ from the ConnectAsync method when an app uses the BindEndpointAsync or BindServiceNameAsync method to bind to a local service name or UDP port. With the GetOutputStreamAsync methods, the app will receive packets from any remote destination sent to the local service name or UDP port. With the ConnectAsync methods, the app will only receive packets from the remote destination passed as parameters to the ConnectAsync methods.