LocationServiceSoap.GetPositions Method
Returns user's or contact's positions synchronously as an instance of the PositionResults class.
Public Function GetPositions (domainAliases As System.String())
_ As PositionResults
[C#]
public PositionResults GetPositions (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.Domain and alias pairs that are passed to this method that exceed the maximum concurrent location requests are ignored. The position result status for the domain and alias pairs that are ignored is set to Failed. The domain and alias pairs that are accepted are placed in the queue if the provider is serving other requests. The number of domain and alias pairs that can be placed in the queue depends on the available depth of the queue; that is, the maximum depth of the queue minus the number of requests already in the queue. All other domain and alias pairs are rejected with a position result status of ProviderBusy.
For example, suppose that the maximum concurrent request limit is 6 and maximum queue limit is 10. If you initiate a request with an array of 10 domain and alias pairs, the provider initially rejects the last 4 of the 10 with a status set to Failed. If the provider is already busy processing other requests, it attempts to place the 6 remaining domain and alias pair into the queue. But if the queue already holds 5 requests from other users, only the first 5 domain and alias pairs are queued and the last is rejected with a status of ProviderBusy.
Remarks
Only one call to the GetPositions method is allowed for each provisioned user at a given time. If you invoke this method while an existing call is in progress, the existing call is aborted and the returned value of the request status is set to Aborted.
The standard time-out limit for this method is 75 seconds and cannot be changed). If the method call takes more than 75 seconds, the GetPositions request is aborted.
The number of positions can be found from the PositionsFound property of the PositionResults object returned by this method.
The status of the request can be found from the RequestStatus property of the PositionResults object. If a call to this method is not aborted, the status is always set to Completed.
This method accepts the following Simple Object Access Protocol (SOAP) headers:
UserInfoLocationHeader—Used to establish the current user's (the user that is invoking the location service) specific information such as culture, and so on. When this SOAP header is not provided, the current user's default culture is applied. For more information about this class, see UserInfoLocationHeader Class.
ClientIdHeader—Not used with MapPoint Location Server 1.0.
This method throws a SOAP exception if one of the following conditions exist:
A user is not provisioned.
A user is not a member of calling user's contact list.
Because this is a Web service, all exceptions appear as SOAP exceptions. For more information , 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 positions from the GetPositions method
Dim MyPositionResults As PositionResults = MyLocationService.GetPositions(New String() {"domain\user"})
'Process the positions here.
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 position from the GetPositions method.
PositionResults MyPositionResults = MyLocationService.GetPositions(new string[] {@"domain\user"});
//Process the positions here.
}
catch(System.Web.Services.Protocols.SoapException MyException)
{
//Your exception processing goes here.
}
See Also
GetPositionsAsync Method | GetContacts Method | PositionResults Class | Location Service Class | UserInfoLocationHeader Class | Contact Definition | Visible Definition | Using Soap Headers