PartyNetwork::CreateEndpoint

Queues an asynchronous attempt to create a local endpoint.

Syntax

PartyError CreateEndpoint(  
    const PartyLocalUser* localUser,  
    uint32_t propertyCount,  
    const PartyString* keys,  
    const PartyDataBuffer* values,  
    void* asyncIdentifier,  
    PartyLocalEndpoint** localEndpoint  
)  

Parameters

localUser   PartyLocalUser*
optional

An optional local user to associate as the owner of this endpoint. When this endpoint becomes visible on remote devices, the user's identifier is tied to this endpoint. The endpoint will be destroyed if the user becomes unauthenticated because they were voluntarily removed via RemoveLocalUser() or kicked via PartyNetwork::KickUser().

propertyCount   uint32_t

The number of properties in the input keys and values arrays.

keys   PartyString*
optional input array of size propertyCount

The propertyCount entry array of property bag keys. The nth key in this array maps to the nth value in the values array. This parameter must be nullptr if propertyCount is 0.

values   PartyDataBuffer*
optional input array of size propertyCount

The propertyCount entry array of property bag values. The nth value in this array is mapped by the nth key in the keys array. This parameter must be nullptr if propertyCount is 0.

asyncIdentifier   void*
optional

An optional, app-defined, pointer-sized context value that can be used to associate the completion state change with this call.

localEndpoint   PartyLocalEndpoint**
optional, library-allocated output

The optional, output local endpoint object on which to queue endpoint operations.

Return value

PartyError

c_partyErrorSuccess if the asynchronous operation to create the endpoint began, or an error code otherwise. If this method fails, no related state changes are generated. The human-readable form of the error code can be retrieved via PartyManager::GetErrorMessage().

Remarks

This method queues an asynchronous attempt to create an endpoint associated with the local device on this network. A PartyCreateEndpointCompletedStateChange will be provided upon completion of the operation, indicating success or failure. On success, a PartyEndpointCreatedStateChange will be generated, and the endpoint will be fully created, connected to the network, and visible to all authenticated devices in the network. On failure, a PartyEndpointDestroyedStateChange will be generated.

This method optionally provides localEndpoint as output that can immediately be used to perform asynchronous endpoint operations, such as PartyLocalEndpoint::SendMessage() and PartyLocalEndpoint::SetSharedProperties(). These asynchronous operations are internally queued until the endpoint creation completes, at which point they will be processed. PartyEndpoint::GetUniqueIdentifier() returns a failure until the endpoint creation completes. This localEndpoint will also be provided in the resulting PartyCreateEndpointCompletedStateChange.

A local user may optionally be provided as the owner of an endpoint. If an owning local user is provided, it must be authenticated into the network or in the process of authenticating into the network. If its authentication fails, the endpoint creation will fail as well. If the owning local user is removed from the network while this endpoint exists, the endpoint will be automatically destroyed. This will be signaled via a PartyEndpointDestroyedStateChange.

If the local device enters a state in which there are no authenticated users and no authentication operations in progress, then all endpoints, including those that are not fully created, are destroyed automatically. This will be signaled by PartyEndpointDestroyedStateChanges.

On successful return, this method invalidates the memory for any array previously returned by GetEndpoints(), as it synchronously adds the new endpoint to the array. PartyManager::StartProcessingStateChanges() also invalidates the memory for the array. The returned localEndpoint object remains valid until a PartyEndpointDestroyedStateChange has been generated and all state changes referencing the object have been returned to PartyManager::FinishProcessingStateChanges().

The property bag is a collection of title-specific values associated with an endpoint. The initial property bag is queryable as soon as the endpoint becomes visible.

If a client would violate the PartyNetworkConfiguration::maxEndpointsPerDeviceCount limit by calling this method after the network configuration was made available, this operation fails synchronously. If the client queues a violating number of endpoint creations before the network configuration becomes available, the client will be kicked from the network and a PartyNetworkDestroyedStateChange will be generated when the network configuration becomes available.

Requirements

Header: Party.h

See also

PartyNetwork
PartyCreateEndpointCompletedStateChange
PartyEndpointCreatedStateChange
PartyEndpointDestroyedStateChange
PartyNetworkDestroyedStateChange
PartyNetworkConfiguration
PartyNetwork::GetEndpoints
PartyLocalEndpoint::SendMessage
PartyEndpoint::GetUniqueIdentifier
PartyEndpoint::GetEntityId
PartyEndpoint::GetSharedProperty
PartyNetwork::AuthenticateLocalUser
PartyNetwork::RemoveLocalUser