SecureDeviceAssociationTemplate.CreateAssociationAsync Method

Begins establishing a new secure device association with the device specified by SecureDeviceAddress.

Syntax

public:
IAsyncOperation<SecureDeviceAssociation^ >^ CreateAssociationAsync(
         SecureDeviceAddress^ secureDeviceAddress,
         CreateSecureDeviceAssociationBehavior behavior
)

Parameters

secureDeviceAddress
Type: SecureDeviceAddress

A pointer to the SecureDeviceAddress to which to establish an association.

behavior
Type: CreateSecureDeviceAssociationBehavior

Flags describing how the SecureDeviceAssociation should be established.

Return value

Type: IAsyncOperation<SecureDeviceAssociation^ >

Returns an IAsyncOperation<TResult> object that represents the state of the asynchronous operation. Completion of the asynchronous operation is signaled by using a handler that is passed to the IAsyncOperation<TResult>.Completed property. When the asynchronous operation is complete, the result of the operation can be retrieved by using the IAsyncOperation<TResult>.GetResults method.
The result of the asynchronous operation is a SecureDeviceAssociation object representing a logical connection between two Xbox LIVE authenticated consoles, or between a console and a server.

Remarks

This function begins establishing a secure device association to the remote device indicated by SecureDeviceAddress. When this attempt is completed, the asynchronous operation is completed with the result code. If the association was established successfully, a representative SecureDeviceAssociation object is returned that can be used to perform subsequent socket operations to establish a TCP connection or send and receive UDP messages.

If CreateAssociationAsync is called with the behavior set to CreateSecureDeviceAssociationBehavior.Default and a secure device association for the template has already been established with the remote device specified by the SecureDeviceAddress, either by calling CreateAssociationAsync or by receiving an AssociationIncoming notification, then the operation will successfully complete and return the existing SecureDeviceAddress object without raising an AssociationIncoming notification on the remote device. Alternatively, if the CreateSecureDeviceAssociationBehavior.Reevaluate flag is specified, this method will re-evaluate all potential network paths according to the template’s quality requirements. If the same network path is selected again, the operation still returns the same SecureDeviceAddress object. If a different network path is chosen, the SecureDeviceAssociation object previously returned is implicitly marked as destroyed, and the operation returns a new one. Your code must stop communicating with the peer by using the old socket address retrieved from the previous object and start using addresses from the new secure device association. If your code had established TCP connections to the old address, they are terminated, and your code must reconnect to the new socket address for further TCP communication.

Establishing (or failing to establish) a secure device association is frequently a long operation, occasionally taking 30 seconds or more in some scenarios, depending on network connectivity and template requirements. Titles should avoid blocking on the CreateAssociationAsync operation, typically by creating associations to multiple peer SecureDeviceAddress objects simultaneously or prior to them actually being required.

Successfully established SecureDeviceAssociation objects can be subsequently removed using their DestroyAsync methods. Established SecureDeviceAssociation objects can also change state due to operations outside of the local title’s control, such as the remote device destroying the SecureDeviceAssociation or ungracefully disconnecting from the network. Your code can use the State property to determine current state of the secure device association, or register a SecureDeviceAssociationStateChange event handler to be notified when state changes occur.

Although the system will detect connectivity loss that causes failure of the secure device association, the detection mechanism is designed to add very low network overhead as well as tolerate brief, sporadic problems, such as intermittent wireless signal obstructions. This tolerance means it may take several minutes to detect the peer’s absence in many scenarios. Developers typically want their apps to react more aggressively to potential user experience interruptions, and developers should consider implementing their own connection loss detection via socket-level communication.

Remote peers that accept requests to establish a secure device association can be notified of the new association via a previously-registered SecureDeviceAssociationIncoming event handler. Alternatively, the source address of the UDP message or TCP connection also identifies the specific secure device association, which can be mapped using SecureDeviceAssociation.GetAssociationByHostNamesAndPorts or SecureDeviceAssociation.GetAssociationBySocketAddressBytes.

Two devices should not simultaneously initiate CreateAssociationAsync operations to each other. Simultaneous operations like this might appear to succeed, but will fail later with an error or a silent failure to transmit. When your code is establishing connections between two endpoints, it should ensure that the SecureDeviceAssociation will only be initiated from one of the endpoints, and that the other endpoint will wait for a notification of an incoming association. Your code should use session information to determine which endpoint establishes the association and which waits for notification.

Note CreateAssociationAsync should not overlap with a call to MeasureQualityOfServiceAsync for the same SecureDeviceAddress. Overlapping calls may cause the Secure Device Association creation to fail silently. Both asynchronous operations should be performed sequentially.

Requirements

Namespace: Windows.Xbox.Networking

Metadata: windows.winmd