A UserEndpointinstance can be used for real users represented as Active Directory domain services user objects.

UserEndpointinstances can be created from client-mode or server-mode CollaborationPlatformobjects. When a UserEndpointis established, it registers with a server running Microsoft Office Communications Server. This connection to the server is cached and is used for all outgoing communications. The endpoint registration is refreshed periodically to maintain registered status. In the event of a connection drop, the endpoint attempts to recover by refreshing the registration (by default, the endpoint’s status changes to Terminated). If a refresh fails, however, the endpoint is terminated. If the registration recovers, existing subscriptions are refreshed and the RepublishingRequiredevent might be raised. As long as the endpoint’s Stateproperty is set to Established, all presence services are available to it.

Important:
If a UserEndpointis used with a server-mode CollaborationPlatforminstance in a high-scale application, the application should set the IsEndpointThrottledon SipEndpointto false. The following code example shows how to do this for an existing UserEndpointinstance named userEP.

	Copy Code
SipEndpoint sipEP = userEP.InnerEndpoint; sipEP.IsEndpointThrottled = false;

Several methods and properties on the UserEndpointclass appear in the next code example.

	Copy Code
public UserEndpoint( CollaborationPlatform platform, UserEndpointSettings settings); // Gets or sets the credential needed to authenticate the endpoint with servers. public NetworkCredential Credential{get;set;} // Gets the service used to access or update contact/group information for this endpoint. public ContactGroupServices ContactGroupServices{get;} // Gets the phone URI of the endpoint. public override string OwnerPhoneUri{get;} // Gets the TelephonyMode for the endpoint. public string TelephonyMode{get;} // Gets the value that indicates whether the user is Unified Messaging-enabled. public bool UmEnabled{get;}

Copy Code

public UserEndpoint(
	CollaborationPlatform platform, 
	UserEndpointSettings settings);


// Gets or sets the credential needed to authenticate the endpoint
with servers.
public NetworkCredential Credential{get;set;}

// Gets the service used to access or update contact/group
information for this endpoint.
public ContactGroupServices ContactGroupServices{get;}

// Gets the phone URI of the endpoint.
public override string OwnerPhoneUri{get;}

// Gets the TelephonyMode for the endpoint.
public string TelephonyMode{get;}

// Gets the value that indicates whether the user is Unified
Messaging-enabled.
public bool UmEnabled{get;}

The following table lists several frequently-used members of the UserEndpointclass.

Member	Description
Credential	Gets the credentials for an endpoint. The credential is needed whenever a CollaborationPlatforminstance is configured to use SipTransportType.Tcp. When a user endpoint is challenged by the server, the endpoint supplies its credential for authentication purposes. The user endpoint is configured so that it will fail registration if it is not challenged by a server. If a server-type CollaborationPlatforminstance is configured with MTLS, a credential is not needed.
ContactGroupServices	Gets the service that is used to access and update contact information for this endpoint.
OwnerUri	Gets the URI configured for this user.
OwnerPhoneUri	Gets the phone URI configured for this user. If the Presence publishing service has not yet been established (that is, if the PresencePublishingServicesproperty is not set), an empty string is returned. An empty string will also be returned if a phone number is not found in the UserProperties category.
TelephonyMode	Gets the telephony mode configured for this user. If the Presence publishing service has not yet been established (that is, if the PresencePublishingServicesproperty is not set), an empty string is returned. An empty string will also be returned if a telephonyMode is not found in the UserProperties category.
UmEnabled	Gets the value that indicates whether the user is enabled for Unified Messaging. If the Presence publishing service has not yet been established (that is, if the PresencePublishingServicesproperty is not set), UmEnabledreturns false. This property is trueif UserProperties.ExUmEnabledFeatureshas its lowest-order bit set.

Creating a UserEndpoint Instance

The following example shows how to create a UserEndpointinstance. The steps involve creating a CollaborationPlatforminstance, creating a UserEndpointinstance, setting the credentials on the endpoint, and then establishing the endpoint.

	Copy Code
UserEndpointSettings settings = new UserEndpointSettings("sip:user1@domain", serverFqdn, serverPort); // Set credentials if the platform does not use MTLS. settings.Credential = CredentialCache.DefaultNetworkCredentials; UserEndpoint userEndpoint = new UserEndpoint(platform, settings); userEndpoint.BeginEstablish(EndEndpointEstablish, _userEndpoint); void EndEndpointEstablish(IAsyncResult ar) { UserEndpoint userEndpoint = ar.AsyncState as UserEndpoint; try { userEndpoint.EndEstablish(ar); Console.WriteLine("The User Endpoint owned by URI: "); Console.WriteLine(userEndpoint.OwnerUri); Console.WriteLine(" is now established and registered."); } catch (ConnectionFailureException connFailEx) { // ConnectionFailureException will be thrown when the endpoint cannot connect to the server, or the credentials are invalid. // It is left to the developer to write real error-handling code. Console.WriteLine(connFailEx.ToString()); } catch (InvalidOperationException iOpEx) { // InvalidOperationException will be thrown when the endpoint is not in a valid state to connect. To connect, the platform must be started and the Endpoint Idle. // It is left to the developer to write real error-handling code. Console.WriteLine(iOpEx.ToString()); } catch (RegisterException regEx) { // RegisterException will be thrown when the endpoint cannot be registered (usually due to bad credentials). // It is left to the developer to write real error-handling code (here, the appropriate action is likely reprompting for user/password/domain strings). Console.WriteLine(regEx.ToString()); } }

Copy Code

UserEndpointSettings settings = new
UserEndpointSettings("sip:user1@domain", serverFqdn, serverPort);

// Set credentials if the platform does not use MTLS.
settings.Credential = CredentialCache.DefaultNetworkCredentials;

UserEndpoint userEndpoint = new UserEndpoint(platform, settings);

userEndpoint.BeginEstablish(EndEndpointEstablish, _userEndpoint);

void EndEndpointEstablish(IAsyncResult ar)
{
  UserEndpoint userEndpoint = ar.AsyncState as UserEndpoint;
  try
  {
	userEndpoint.EndEstablish(ar);
	Console.WriteLine("The User Endpoint owned by URI: ");
	Console.WriteLine(userEndpoint.OwnerUri);
	Console.WriteLine(" is now established and registered.");
  }
  catch (ConnectionFailureException connFailEx)
  {
	// ConnectionFailureException will be thrown when the endpoint
cannot connect to the server, or the credentials are invalid.
	// It is left to the developer to write real error-handling
code.
	Console.WriteLine(connFailEx.ToString());
  }
  catch (InvalidOperationException iOpEx)
  {
	// InvalidOperationException will be thrown when the endpoint
is not in a valid state to connect. To connect, the platform must
be started and the Endpoint Idle.
	// It is left to the developer to write real error-handling
code.
	Console.WriteLine(iOpEx.ToString());
  }
  catch (RegisterException regEx)
  {
	// RegisterException will be thrown when the endpoint cannot be
registered (usually due to bad credentials).
	// It is left to the developer to write real error-handling
code (here, the appropriate action is likely reprompting for
user/password/domain strings).
	Console.WriteLine(regEx.ToString());
  }

}

UserEndpointSettings Class

The UserEndpointSettingsclass is used to initialize a UserEndpointinstance when it is created.

UserEndpointSettings Constructors

The UserEndpointSettingsclass has the following constructors.

	Copy Code
// Creates a new instance of the UserEndpointSettings class. public UserEndpointSettings(string ownerUri, string serverName); // Creates a new instance of the UserEndpointSettings class. public UserEndpointSettings(string ownerUri, string serverName, int serverPort);

Copy Code

// Creates a new instance of the UserEndpointSettings class.
public UserEndpointSettings(string ownerUri, string serverName);

// Creates a new instance of the UserEndpointSettings class.
public UserEndpointSettings(string ownerUri, string serverName, int
serverPort);

UserEndpointSettings Properties

The following are the public properties on the UserEndpointSettings class.

	Copy Code
// Gets the name of the server being used. public string ServerName {get;} // Gets the port of the server being used. public int ServerPort {get;} // Gets or sets the endpoint ID (EPID) to use for the endpoint. Optional. public string EndpointId {get; set;} // Gets or sets the credential needed to authenticate the endpoint with servers. // Use CredentialCache.DefaultNetworkCredentials for a logged-on user. public NetworkCredential Credential {get; set;}

Copy Code

// Gets the name of the server being used.
public string ServerName {get;}

// Gets the port of the server being used.
public int ServerPort {get;}

// Gets or sets the endpoint ID (EPID) to use for the endpoint.
Optional.
public string EndpointId {get; set;}

// Gets or sets the credential needed to authenticate the endpoint
with servers.
// Use CredentialCache.DefaultNetworkCredentials for a logged-on
user.
public NetworkCredential Credential {get; set;}