TdxMapControlAzureMapRouteProvider.Execute(IdxAzureMapRouteQueryParams,TdxAzureMapRouteRequestResponse) Method

Sends a query to an Azure Maps server and returns the result.

Declaration

procedure Execute(const AParams: IdxAzureMapRouteQueryParams; out ARouteResponse: TdxAzureMapRouteRequestResponse);

Parameters

Name	Type	Description
AParams	IdxAzureMapRouteQueryParams	Accepts a configured query parameters container. Call the CreateQueryParams function to create a query parameters container.
ARouteResponse	TdxAzureMapRouteRequestResponse	Returns a container populated with information returned by a server. Important Every Execute procedure call creates a new TdxAzureMapRouteRequestResponse class instance. Call the Free procedure (in Delphi) or use the delete keyword (in C++Builder) to destroy TdxAzureMapRouteRequestResponse class instances manually to avoid memory leaks.

Remarks

Call the Execute procedure to send a route query to an Azure Maps server and wait for a response returned as the ARouteResponse parameter.

Code Example: Draw a Map Route

The following code example uses a configured information provider to draw a route between two specified points on a map:

Delphi

uses
  dxAzureMapInformationProviders,  // Declares TdxMapControlAzureMapRouteProvider
  dxCoreGraphics;  // Declares TdxAlphaColors
// ...

procedure TMyForm.DrawMapRoute(ARouteStart, ARouteEnd: TdxMapControlGeoPoint);
var
  APolyline: TdxMapPolyline;
  ARoute: TdxAzureMapRouteItem;
  AParams: IdxAzureMapRouteQueryParams;
  AResponse: TdxAzureMapRouteRequestResponse;
  ARouteWaypoints: TdxMapControlGeoPoints;
  I, J: Integer;
begin
  AParams := dxMapControl1AzureMapRouteProvider1.CreateQueryParams;
  SetLength(ARouteWaypoints, 2);
  ARouteWaypoints[0] := ARouteStart;
  ARouteWaypoints[1] := ARouteEnd;
  AParams.WayPoints := ARouteWaypoints;
  AParams.TravelMode := TdxAzureMapRouteTravelMode.Car;
  AParams.MaxAlternatives := 1;
  dxMapControl1AzureMapRouteProvider1.Execute(AParams, AResponse);
  dxMapControl1.BeginUpdate;  // Initiates the following batch change
  try
    if AResponse <> nil then
    begin
      if AResponse.IsSuccess then  // Draws a route if a valid server response is received
      begin
        APolyline := dxMapControl1ItemLayer1.AddItem(TdxMapPolyline) as TdxMapPolyline;
        ARoute := AResponse.Routes.Items[0];  // Selects the first returned route
        for I := 0 to ARoute.Legs.Count - 1 do
          for J := 0 to ARoute.Legs.Items[I].Points.Count - 1 do
            APolyline.GeoPoints.Add.GeoPoint := ARoute.Legs.Items[I].Points.Items[J];

        APolyline.Style.BorderWidth := 4;
        APolyline.Style.BorderColor := TdxAlphaColors.DarkBlue;
      end;
    end;
  finally
    dxMapControl1.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

C++

#include "dxAzureMapInformationProviders.hpp"  // Declares TdxMapControlAzureMapRouteProvider
#include "dxCoreGraphics.hpp"  // Declares TdxAlphaColors
// ...

void __fastcall TMyForm::ValidateServerResponse(TdxMapControlGeoPoint *ARouteStart,
  TdxMapControlGeoPoint *ARouteEnd)
{
  TdxMapItem *AMapItem;
  TdxMapPolyline *APolyline;
  TdxAzureMapRouteItem *ARoute;
  _di_IdxAzureMapRouteQueryParams AParams;
  TdxAzureMapRouteRequestResponse *AResponse;
  TdxMapControlGeoPoints *ARouteWaypoints;

  AParams = dxMapControl1AzureMapRouteProvider1->CreateQueryParams();
  SetLength(ARouteWaypoints, 2);
  ARouteWaypoints[0] = ARouteStart;
  ARouteWaypoints[1] = ARouteEnd;
  AParams->WayPoints = ARouteWaypoints;
  AParams->TravelMode = TdxAzureMapRouteTravelMode::Car;
  AParams->MaxAlternatives = 1;
  dxMapControl1AzureMapRouteProvider1->Execute(AParams, AResponse);
  dxMapControl1->BeginUpdate();  // Initiates the following batch change
  try
  {
    if(AResponse != nullptr)
    {
      if(AResponse->IsSuccess)  // Draws a route if a valid server response is received
      {
        AMapItem = dxMapControl1ItemLayer1->AddItem(__classid(TdxMapPolyline));
        APolyline = dynamic_cast<TdxMapPolyline*>(AMapItem);
        ARoute = AResponse->Routes->Items[0]; // Selects the first returned route
        for(int i = 0; i < ARoute->Legs->Count; i++)
          for(int j = 0; j < ARoute->Legs->Items[i]->Points->Count; j++)
            APolyline->GeoPoints->Add()->GeoPoint = ARoute->Legs->Items[i]->Points->Items[j];

        APolyline->Style->BorderWidth = 4;
        APolyline->Style->BorderColor = TdxAlphaColors::DarkBlue;
      }
    }
  }
  __finally
  {
    dxMapControl1->EndUpdate();  // Calls EndUpdate regardless of tha batch operation's success
  }
}

Asynchronous Queries and Server Responses

The Execute procedure runs in the main thread and, therefore, locks the application UI until the corresponding server response or a timeout error.

To keep your UI responsive, you can call the ExecuteAsync procedure instead. Handle the OnResponse event to process a server response when the information provider receives it.