ServerAPI.FindProvisionedUser Method

  • Article

Allows partial input of LocatableUser object properties or an e-mail address of a user to search provisioned MapPoint Location Server users and returns contact information as an array of LocatableContact instances.

Public Function FindProvisionedUser (user As Microsoft.MapPoint.LocationServer.Types.ProvisionedUser, _      locatablePhoneNumber As Microsoft.MapPoint.LocationServer.Types.LocatablePhoneNumber, _      maxResults As System.Int32, _      culture As System.String)

      _ As Microsoft.MapPoint.LocationServer.Types.LocatableContact()
[C#]
public Microsoft.MapPoint.LocationServer.Types.LocatableContact[] FindProvisionedUser (Microsoft.MapPoint.LocationServer.Types.ProvisionedUser user,      Microsoft.MapPoint.LocationServer.Types.LocatablePhoneNumber locatablePhoneNumber,      System.Int32 maxResults,      System.String culture);

Parameters

  • user
    A ProvisionedUser object containing information (such as domain and alias, locatable phone number, e-mail address, and so on) that is used to search for a contact. Provide one of the following values to search for: domain alias

    e-mail address

    display name

    first and last name combination

    This list is in order of precedence.

    This search yields results only when there is an exact match for one of the given values.

  • locatablePhoneNumber
    A locatable phone number for a provisioned user, as a LocatablePhoneNumber object. This parameter is optional. When null is passed for this parameter, the search is performed based on only the user parameter.

    To search for a contact based on a phone number, you must provide the short number (the last 7 digits of the 10 digit phone number) .

    When a locatable phone number is provided with a proper short number, an exact match search is performed.

  • maxResults
    The maximum number of locatable contacts to return as a result of a search. This value must be greater than or equal to -1.

    When you set this parameter to -1, all provisioned users matching the criteria are returned.

    If a search returns more contacts than specified by maxResults, an exception is thrown.

  • culture
    The culture name in the format "languagecode2-regioncode2", where languagecode2 is a lowercase two-letter code derived from ISO 639-1 and regioncode2 is an uppercase two-letter code derived from ISO 3166. For example, "en-US" denotes English (United States). When no culture value is passed (a null value), the culture of the current thread is taken as the default culture. This culture is used to sort the results (provisioned users that are returned with this method).

Remarks

A provisioned user account can contain partial information (only a few properties set).
Use the following rules to search for a provisioned user:

Domain and alias:

Partial domain and alias searching is permitted. For example, in a search for a user, "Paula J. Flanders", in the domain, "fourthcoffee", with the alias, "paula", the following cases return valid results:

Searching for "paula" returns an exact match for "fourthcoffee\paula"

Searching for "fourthcoffee\paula" returns an exact match for "fourthcoffee\paula".

Searching for "fourthcoffee/paula" returns an exact match for "fourthcoffee\paula".

The following searches fail to return the provisioned user:

Searching for "flanders" fails (assuming that the alias "flanders" does not belong to another valid user.)

Searching for "pjf" fails (assuming that the alias "pjf" does not belong to another valid user.)

Display names:

Partial display name searching is performed using a "starts-with" condition. For example, if the display name is "Ms. Paula Flanders," searching for "Paula" yields "Ms. Paula Flanders" as one of the results.

At least two characters must be supplied for a search with a partial display name.

First and last names:

Partial searching is allowed for first and last name searches. The sum of the characters from both the first name and last name must be greater than or equal to two. The following searches return results for "Paula Flanders":

Searching for "Paula" as the first name and "Flanders" as the last name returns "Paula Flanders" as one of the matches.

Searching for "P" as first name and "Flanders" as last name returns "Paula Flanders" as one of the matches.

Searching for "Paula" as the first name and "F" as the last name returns "Paula Flanders" as one of the matches.

Searching for "Paula" as the first name and "" (empty) as the last name returns "Paula Flanders" as one of the matches (or may fail if too many matches are returned.)

Finally, searching for "P" as the first name and "F" as the last name may fail because too many matches may be returned.

Phone number:

The locatablePhonenumber parameter is optional and can be null.

When a phone number is provided, an exact match is returned (assuming the phone number exists in the database).

The short number (the last seven digits of the phone number) must be provided in order to be considered for a search.

E-mail address:

E-mail address searches allow a "starts-with" partial search. However, if you provide the complete e-mail address including an "@" sign, an exact match is returned (assuming the e-mail address exists in the database).

If no valid search criteria is provided, a NoFindCriteriaException is thrown.

Example

 
[Visual Basic]
    'Microsoft SQL Server and database instance names. 
    Const server As String = "Your SQL Server Name"
    Const database As String = "LocationServerDB"
    'Create a ServerAPI instance. 
    Dim MyServerAPI As New ServerAPI
    Try
        'Call initialize. 
        Call MyServerAPI.Initialize(server, database)
    Catch MyException As SqlConnectionFailedException
        'Your exception processing goes here.. 
    End Try
    'If Initialize method call is successful, 
    'create a provisioned user instance and 
    'assign the search value. 
    Dim MyProvisionedUser As ProvisionedUser = New ProvisionedUser
    MyProvisionedUser.DomainAlias = "DOMAIN\user"
    'Create a locatable devide instance and assign the value. 
    Dim MyLocatableEndPoint As LocatablePhoneNumber = New LocatablePhoneNumber
    MyLocatableEndPoint.CountryCode = "001"
    MyLocatableEndPoint.LocalCode = "111"
    MyLocatableEndPoint.ShortNumber = "1111111"
    'Now find out if this user is provisioned. 
    Try
        Dim users As LocatableContact() = MyServerAPI.FindProvisionedUser(MyProvisionedUser, MyLocatableEndPoint, -1, "en-US")
        For Each user As LocatableContact In users
            Console.WriteLine(user.DisplayName)
        Next
    Catch MyException As Exception
        'Your exception processing goes here. 
    End Try

 
[C#]
  //Set the computer running SQL Server and database instance names 
  const string server = "Your SQL Server Name"; 
  const string database = "LocationServerDB"; 
  //Create a ServerAPI instance. 
  ServerAPI MyServerAPI = new ServerAPI(); 
  try
  { 
   //Call initialize. MyServerAPI.Initialize(server, database); 
  }
  catch(SqlConnectionFailedException MyException) 
  { 
   //Your exception processing goes here. 
  } 
  //If Initialize method call is successful, 
  //create a provisioned user instance and 
  //assign the search value. 
  ProvisionedUser MyProvisionedUser = new ProvisionedUser(); 
  MyProvisionedUser.DomainAlias = @"DOMAIN\user";
  //Create a locatable devide instance and assign the value. 
  LocatablePhoneNumber MyLocatableEndPoint = new LocatablePhoneNumber(); 
  MyLocatableEndPoint.CountryCode = "001";
  MyLocatableEndPoint.LocalCode = "111"; 
  MyLocatableEndPoint.ShortNumber = "1111111"; 
  //Now find out if this user is provisioned. 
  try 
  { 
   LocatableContact[] users = MyServerAPI.FindProvisionedUser(MyProvisionedUser, MyLocatableEndPoint, -1, "en-US");
   foreach(LocatableContact user in users) 
  { 
   Console.WriteLine(user.DisplayName);
  } 
  }
  catch(Exception MyException) 
  { 
   //Your exception process goes here.. 
  } 
   
  
 

See Also

LocatableContact Class  |  LocatablePhoneNumber Class  |  Microsoft.MapPoint.LocationServer.Management  |  ProvisionedUser Class  |  ServerAPI Class  |  ServerAPI Members  |  ServerAPIException Class