Endpoint.Name Property

Gets or sets the endpoint's name.

Script:  http://www.wlmessenger.net/api/3.7/loader.js
Feature:  Messenger.Core
Namespace:  Microsoft.Live.Messenger
 

// To retrieve:
var name = instance.get_name();

// To update:
instance.set_name(value);

Applications should set the local endpoint name to identify the local endpoint. The endpoint name is shared with the user's other endpoints. The name can be useful when listing the currently signed in endpoints for a user. For the endpoints of a user's contacts, Name always returns String.Empty.

By default, the local endpoint's name is initialized to the domain name that hosts the application. If an application accepts user input for all or part of the endpoint name, the IsNameValid(String) method should be used to validate the input.

The following example demonstrates enumerating through the endpoint names in a user's endpoint collection.


             // Create an array to track the current endpoint names. For simplicity, this could represent the
             // variable that the application is using to populate a DIV or other HTML element.
             var currentEndpointNames = [];
             
             // This function creates a new instance of the Sign-in Control. It is run when the page loads.
             function scriptMain() {
                 var privUrl = 'http://' + document.domain + '/Privacy.htm';
                 var chanUrl = 'http://' + document.domain + '/Channel.htm';
                 _signin = new Microsoft.Live.Messenger.UI.SignInControl('signinframe', privUrl, chanUrl, 'en-US');
                 _signin.add_authenticationCompleted(authenticationCompleted);
             }
             
             // Called by the Messenger Library when the user authentication process is complete.
             // This is where the SignIn method is called.
             function authenticationCompleted(sender, e) {
                 _user = new Microsoft.Live.Messenger.User(e.get_identity());
                 _user.add_signInCompleted(signInCompleted);
                 _user.signIn();
             }
                 
             // This function is invoked when sign-in completes.
             function signInCompleted(sender, e)
             {
                 // Get the current endpoint collection.
                 var endpoints = _user.get_endpoints();
                 
                 // If the endpoint collection changes in the future, we want to be notified so that the
                 // current endpoint names can be updated.
                 endpoints.add_collectionChanged(endpointsCollectionChanged);
                 
                 // Update the endpoint names.
                 updateEndpointNames(endpoints);
             }
                 
             // This function is invoked whenever the endpoint collection changes.
             function endpointsCollectionChanged(sender, e)
             {
                 var endpoints = (EndpointCollection)sender;
             
                 updateEndpointNames(endpoints);
             }
            
             // This function is invoked whenever we need to update the current list of endpoint names that the
             // application is tracking.
             function updateEndpointNames(endpoints)
             {
                 // Reset the current endpoint names collection.
                 currentEndpointNames = [];
                 
                 // Iterate through the endpoint collection and update the endpoint names.
                 for (var i=0; i < endpoints.get_count(); i++)
                 {
                     currentEndpointNames.add(endpoints.get_item(i).get_name();
                 }
             }
             

The following example demonstrates updating the user's local endpoint name to the name of the application.


             var endpoint = user.get_localEndpoint();
             var newEndpointName = 'Contoso';
            
             if (Microsoft.Live.Messenger.Endpoint.isNameValid(newEndpointName))
             {
                 endpoint.set_name(newEndpointName);
             }
             

ExceptionCondition
ExceptionThe property is set and value is a null reference.
ExceptionThe property is set and the format of value is invalid.
ExceptionThe property is set and this Endpoint does not correspond to LocalEndpoint.
ExceptionThe property is set and the user is not signed in.

Windows Live Messenger Web Toolkit

Supported in: 3.7, 3.5, 3.1, 3.0, 2.5

Internet Explorer 8.0, Internet Explorer 7.0, Internet Explorer 6.0, Firefox 3.5, Firefox 3.0, Firefox 2.0, Firefox 1.5, Chrome 3.0, Chrome 2.0, Chrome 1.0, Safari 4.0, Safari 3.0

Show: