LocationServiceSoap.GetPositionsAsync Method

Returns user's or contact's positions asynchronously. This method is an asynchronous version of the GetPositions method. However, you must call the GetPositionsAsyncResults method to complete the process of getting positions.

Public Function GetPositionsAsync (domainAliases As System.String())

      _ As System.string
[C#]
public System.string GetPositionsAsync (System.String[] domainAliases);

Parameters

• domainAliases
  A string array of domainAlias names. A maximum of 1,024 domain and alias pairs can be passed to this method. However, the number of domainAlias strings that are accepted by a location provider depend on the following conditions: The number of concurrent location requests that the provider can handle. The number of location requests that can be placed in the queue for the provider.

  All domain aliases passed to this request exceeding the concurrent number supported by the provider are ignored. For the domain aliases that are being ignored, the position result status is set to Failed.
  The domain aliases that are accepted (not ignored) are queued if the provider is busy serving other requests. The number of domain aliases that can be queued depends on the available depth of the queue; that is, the maximum allowed queue depth minus the number of requests already queued.
  Only the domain aliases that can be queued without exceeding the maximum number of location requests that can be queued for the provider are queued. All other domain aliases are rejected with a position result status set to ProviderBusy.

  For example, for a provider, the maximum concurrent request limit is 6 and maximum queue limit is 10.
  If you initiate a request with an array of 10 domain aliases, the provider initially rejects the last 4 of the 10 domain aliases with a status set to Failed.
  If the provider is already busy processing other requests, it attempts to queue the 6 domain aliases of your request. If the queue is already holding about 5 requests from other users, only the first 5 domain aliases are queued and the last domain alias of your 6 accepted domain aliases is rejected with a status ProviderBusy.

Remarks

A call to this method initiates an asynchronous request to get the positions for the specified domain and alias pairs. This method returns a token (as a string), which must be used when calling the GetPositionsAsyncResults method to get the position results.

Only one call to GetPositionsAsync is allowed for each provisioned user at a given time. If you invoke this method while a call is already in progress, the existing call is aborted and returned value of the request status is set to aborted.

This method accepts the following SOAP headers:

UserInfoLocationHeader—Used to establish the current user's (the user that is invoking the location service) specific information, such as culture and default distance unit. When this SOAP header is not provided, the current user's default culture is applied. For more information, see UserInfoLocationHeader Class.

ClientIdHeader—Not used with MapPoint Location Server 1.0.

Because this is a Web service, all exceptions appear as SOAP exceptions. For more information about this exception, see the SoapException.Detail property.

Example

 
[Visual Basic]
    'Create a LocationServiceSoap proxy instance.
    Dim MyLocationService As New LocationServiceSoap
    'Create and add the credentials required to access the Web service. 
    Dim MyCredentials As New NetworkCredential("user", "password", "domain")
    MyLocationService.Credentials = MyCredentials
    Try
        'Get the token from the GetPositionsAsync method
        Dim token As String = MyLocationService.GetPositionsAsync(New String() {"domain\user"})
        'Do some process. 

        'Get the Position Request Results 
        Dim MyPositionResult As PositionResults = MyLocationService.GetPositionsAsyncResults(token)
        'Process the results. 
    Catch ex As System.Web.Services.Protocols.SoapException
        'Your exception processing goes here. 
    End Try

 
[C#]
  //Create a LocationServiceSoap proxy instance. 
  LocationService MyLocationService = new LocationService(); 
  //Create and add the credentials required to access the Web service. 
  NetworkCredential MyCredentials = new NetworkCredential("user", "password", "domain"); 
  MyLocationService.Credentials = MyCredentials; 
  try 
  {
   //Get the token from the GetPositionsAsync method.
   String token = MyLocationService.GetPositionsAsync(new string[] {@"domain\user"});
   //Do some process. 
   //Get the Position Request Results.
   PositionResults MyPositionResult = MyLocationService.GetPositionsAsyncResults(token);
   //Process the results. 
  } 
  catch(System.Web.Services.Protocols.SoapException MyException) 
  { 
   //Your exception processing goes here. 
  }

  
 

See Also

GetPositionsAsyncResults Method  |  GetPositions Method  |  GetContacts Method  |  PositionResults Class  |  Location Service Class  |  UserInfoLocationHeader Class  |  Contact Definition  |  Visible Definition  |  Using Soap Headers