Class BingRestMapProvider

Provides comprehensive map services using Bing Maps REST APIs including tiles, routing, search, elevation, and truck routing capabilities.

Inheritance
System.Object
BingRestMapProvider
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.RadMap.dll

Syntax

public class BingRestMapProvider : IMapProvider, ICloneable, IMapTileProvider, IMapRouteProvider, IMapTruckRouteProvider, IMapSearchProvider, IMapBaseSearchProvider, IMapElevationProvider

Constructors

BingRestMapProvider()

Initializes a new instance of the BingRestMapProvider class with default settings and configures tile downloading and caching.

Declaration
public BingRestMapProvider()

Fields

cacheLoadReference

Declaration
protected Dictionary<string, List<TileInfo>> cacheLoadReference
Field Value
System.Collections.Generic.Dictionary<System.String, System.Collections.Generic.List<TileInfo>>

lockObj

Declaration
protected object lockObj
Field Value
System.Object

tileMatrix

Declaration
protected Dictionary<string, TileInfo> tileMatrix
Field Value
System.Collections.Generic.Dictionary<System.String, TileInfo>

Properties

BingKey

Gets or sets the Bing Maps API key used for authenticating requests to Bing Maps services and enabling premium features.

Declaration
public string BingKey { get; set; }
Property Value
System.String

The bing key.

CacheProvider

Gets or sets the cache provider instance used for storing and retrieving map tiles from local storage.

Declaration
public IMapCacheProvider CacheProvider { get; set; }
Property Value
IMapCacheProvider

Implements

Culture

Gets or sets the culture information used for localizing map content, search results, and routing instructions.

Declaration
public CultureInfo Culture { get; set; }
Property Value
System.Globalization.CultureInfo

The culture.

EnableCaching

Gets or sets a value indicating whether tile caching is enabled for storing downloaded tiles locally to improve performance.

Declaration
public bool EnableCaching { get; set; }
Property Value
System.Boolean

Implements

Id

Gets the unique identifier for this Bing Maps provider instance.

Declaration
public string Id { get; }
Property Value
System.String

Implements

ImagerySet

Gets or sets the Bing Maps imagery set that determines the visual style and content type of map tiles displayed.

Declaration
public ImagerySet ImagerySet { get; set; }
Property Value
ImagerySet

The imagery set.

Initialized

Gets or sets a value indicating whether this BingRestMapProvider has completed initialization and is ready for service calls.

Declaration
public bool Initialized { get; protected set; }
Property Value
System.Boolean

true if initialized; otherwise, false.

Initializing

Gets or sets a value indicating whether this BingRestMapProvider is currently performing initialization operations.

Declaration
public bool Initializing { get; protected set; }
Property Value
System.Boolean

true if initializing; otherwise, false.

MaxZoomLevel

Gets or sets the maximum zoom level supported by this Bing Maps provider for tile requests and map display.

Declaration
public int MaxZoomLevel { get; set; }
Property Value
System.Int32

Implements

MinZoomLevel

Gets or sets the minimum zoom level supported by this Bing Maps provider for tile requests and map display.

Declaration
public int MinZoomLevel { get; set; }
Property Value
System.Int32

Implements

SessionId

Gets the unique session identifier obtained from Bing Maps logging service for optimized API usage and cost reduction.

Declaration
public string SessionId { get; }
Property Value
System.String

The session identifier.

TileDownloader

Gets or sets the tile downloader instance responsible for asynchronously downloading map tiles from Bing Maps service.

Declaration
public IMapTileDownloader TileDownloader { get; set; }
Property Value
IMapTileDownloader

Implements

TileSize

Gets the standard tile size in pixels used by this Bing Maps provider for all tile requests and rendering operations.

Declaration
public Size TileSize { get; }
Property Value
System.Drawing.Size

Implements

UseSession

Gets or sets a value indicating whether to use session-based authentication for improved performance and reduced transaction costs.

Declaration
public bool UseSession { get; set; }
Property Value
System.Boolean

true if session should be used; otherwise, false.

Methods

BuildElevationRequestUri(ElevationRequest)

Constructs the Bing Maps elevation request URI based on the elevation request parameters and elevation type settings.

Declaration
protected virtual Uri BuildElevationRequestUri(ElevationRequest request)
Parameters
ElevationRequest request

The elevation request containing parameters for URI construction.
Returns
System.Uri

The complete URI for the Bing Maps elevation API request.

BuildRoutingRequestUri(RouteRequest)

Constructs the Bing Maps routing request URI based on the route request parameters and travel mode settings.

Declaration
protected virtual Uri BuildRoutingRequestUri(RouteRequest request)
Parameters
RouteRequest request

The route request containing parameters for URI construction.
Returns
System.Uri

The complete URI for the Bing Maps routing API request.

BuildSearchRequestUri(SearchRequest)

Constructs the Bing Maps search request URI based on the search request parameters and localization settings.

Declaration
protected virtual Uri BuildSearchRequestUri(SearchRequest request)
Parameters
SearchRequest request

The search request containing query parameters and search options.
Returns
System.Uri

The complete URI for the Bing Maps search API request.

BuildTruckRouteRequestBody(TruckRouteRequest)

Constructs the JSON request body for truck routing containing waypoints, vehicle specifications, and routing options.

Declaration
protected virtual string BuildTruckRouteRequestBody(TruckRouteRequest request)
Parameters
TruckRouteRequest request

The truck route request containing parameters for JSON body construction.
Returns
System.String

The JSON request body string for the truck routing API call.

BuildTruckRouteRequestUri(TruckRouteRequest)

Constructs the Bing Maps truck routing request URI with authentication parameters for the truck routing service.

Declaration
protected virtual Uri BuildTruckRouteRequestUri(TruckRouteRequest request)
Parameters
TruckRouteRequest request

The truck route request containing routing parameters.
Returns
System.Uri

The complete URI for the Bing Maps truck routing API request.

CalculateElevationAsync(ElevationRequest)

Performs an asynchronous elevation calculation using Bing Maps elevation services with the specified elevation request parameters.

Declaration
public void CalculateElevationAsync(ElevationRequest request)
Parameters
ElevationRequest request

The elevation request containing points, bounds, and elevation calculation options.
Implements

CalculateRouteAsync(RouteRequest)

Performs an asynchronous route calculation using Bing Maps routing services with the specified route request parameters.

Declaration
public void CalculateRouteAsync(RouteRequest request)
Parameters
RouteRequest request

The route request containing waypoints, travel mode, and routing options.
Implements

CalculateTruckRouteAsync(TruckRouteRequest)

Performs an asynchronous truck route calculation using Bing Maps truck routing services with vehicle specifications and restrictions.

Declaration
public void CalculateTruckRouteAsync(TruckRouteRequest request)
Parameters
TruckRouteRequest request

The truck route request containing waypoints, vehicle specifications, and routing constraints.
Implements

Clone()

Creates a deep copy of this BingRestMapProvider instance with all configuration settings and metadata information.

Declaration
public object Clone()
Returns
System.Object

A new BingRestMapProvider object that is a copy of this instance.
Implements
System.ICloneable.Clone()

GetCacheKey(Int32, Int32, Int32)

Generates a unique cache key string for storing and retrieving tile images based on coordinates, zoom level, and imagery set.

Declaration
protected virtual string GetCacheKey(int tileX, int tileY, int zoomLevel)
Parameters
System.Int32 tileX

The tile x.
System.Int32 tileY

The tile y.
System.Int32 zoomLevel

The zoom level.
Returns
System.String

System.String.

GetContent(IMapViewport)

Generates map visual elements for the specified viewport by converting cached tile images into renderable map tile elements.

Declaration
public virtual IEnumerable<MapVisualElement> GetContent(IMapViewport viewport)
Parameters
IMapViewport viewport

The map viewport defining the visible area and zoom level.
Returns
System.Collections.Generic.IEnumerable<MapVisualElement>

An enumerable collection of MapVisualElement objects representing map tiles.
Implements

GetPointsString(List<PointG>)

Converts a list of geographic points into a comma-separated string format for use in elevation API requests.

Declaration
protected virtual string GetPointsString(List<PointG> points)
Parameters
System.Collections.Generic.List<PointG> points

The list of geographic points to convert.
Returns
System.String

A comma-separated string representation of the points in latitude,longitude format.

GetSupportedViews()

Retrieves a list of supported map views based on available Bing Maps imagery sets with localized names and selection state.

Declaration
public virtual List<MapViewInfo> GetSupportedViews()
Returns
System.Collections.Generic.List<MapViewInfo>

A list of MapViewInfo objects representing available Bing Maps imagery sets.
Implements

GetTile(Int32, Int32, Int32)

Constructs the URI for retrieving a specific map tile from Bing Maps service using tile matrix coordinates and zoom level.

Declaration
public Uri GetTile(int tileMatrixX, int tileMatrixY, int zoomLevel)
Parameters
System.Int32 tileMatrixX

The tile matrix x.
System.Int32 tileMatrixY

The tile matrix y.
System.Int32 zoomLevel

The zoom level.
Returns
System.Uri

Uri.

GetTileImage(Int32, Int32, Int32)

Synchronously retrieves a tile image from Bing Maps service or cache using the specified tile matrix coordinates and zoom level.

Declaration
public Image GetTileImage(int tileMatrixX, int tileMatrixY, int zoomLevel)
Parameters
System.Int32 tileMatrixX

The tile matrix X coordinate.
System.Int32 tileMatrixY

The tile matrix Y coordinate.
System.Int32 zoomLevel

The zoom level for the tile.
Returns
System.Drawing.Image

The tile image, or null if the tile cannot be retrieved.
Implements

GetTileInfoImage(TileInfo)

Retrieves the tile image for the specified TileInfo either from cache or by downloading from Bing Maps service.

Declaration
protected virtual void GetTileInfoImage(TileInfo tileInfo)
Parameters
TileInfo tileInfo

The tile information.

Initialize()

Initializes this Bing Maps provider by establishing session authentication and retrieving imagery metadata for tile operations.

Declaration
public virtual void Initialize()
Implements
Exceptions
System.Exception

InitializeImageryMetadataCompleted(Object, DownloadStringCompletedEventArgs)

Handles the completion of imagery metadata initialization by processing service response and configuring tile size and zoom levels.

Declaration
protected virtual void InitializeImageryMetadataCompleted(object sender, DownloadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.DownloadStringCompletedEventArgs e

The System.Net.DownloadStringCompletedEventArgs instance containing the event data.

InitializeImageryService()

Initializes the Bing Maps imagery service by retrieving metadata information for the current imagery set and configuring tile parameters.

Declaration
protected virtual void InitializeImageryService()
Exceptions
System.Exception

InitializeSessionCompleted(Object, DownloadStringCompletedEventArgs)

Handles the completion of session initialization by extracting the session ID and proceeding to initialize imagery services.

Declaration
protected virtual void InitializeSessionCompleted(object sender, DownloadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.DownloadStringCompletedEventArgs e

The System.Net.DownloadStringCompletedEventArgs instance containing the event data.

OnCalculateElevationCompleted(Object, DownloadStringCompletedEventArgs)

Handles the completion of elevation calculation by processing the JSON response and extracting elevation or sea level data.

Declaration
protected virtual void OnCalculateElevationCompleted(object sender, DownloadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.DownloadStringCompletedEventArgs e

The System.Net.DownloadStringCompletedEventArgs instance containing the event data.

OnCalculateElevationCompleted(ElevationCompletedEventArgs)

Raises the CalculateElevationCompleted event to notify subscribers that an elevation calculation has finished successfully.

Declaration
protected virtual void OnCalculateElevationCompleted(ElevationCompletedEventArgs e)
Parameters
ElevationCompletedEventArgs e

The event arguments containing the calculated elevation data.

OnCalculateElevationError(CalculateElevationErrorEventArgs)

Raises the CalculateElevationError event to notify subscribers that an elevation calculation has encountered an error.

Declaration
protected virtual void OnCalculateElevationError(CalculateElevationErrorEventArgs e)
Parameters
CalculateElevationErrorEventArgs e

The event arguments containing the elevation calculation error details.

OnCalculateRouteCompleted(Object, DownloadStringCompletedEventArgs)

Handles the completion of route calculation by processing the JSON response and extracting route information.

Declaration
protected virtual void OnCalculateRouteCompleted(object sender, DownloadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.DownloadStringCompletedEventArgs e

The System.Net.DownloadStringCompletedEventArgs instance containing the event data.

OnCalculateRouteCompleted(RoutingCompletedEventArgs)

Raises the CalculateRouteCompleted event to notify subscribers that a route calculation has finished successfully.

Declaration
protected virtual void OnCalculateRouteCompleted(RoutingCompletedEventArgs e)
Parameters
RoutingCompletedEventArgs e

The event arguments containing the calculated routes.

OnCalculateRouteError(CalculateRouteErrorEventArgs)

Raises the CalculateRouteError event to notify subscribers that a route calculation has encountered an error.

Declaration
protected virtual void OnCalculateRouteError(CalculateRouteErrorEventArgs e)
Parameters
CalculateRouteErrorEventArgs e

The event arguments containing the route calculation error details.

OnCalculateTruckRouteCompleted(Object, UploadStringCompletedEventArgs)

Handles the completion of truck route calculation by processing the JSON response and extracting truck route information.

Declaration
protected virtual void OnCalculateTruckRouteCompleted(object sender, UploadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.UploadStringCompletedEventArgs e

The System.Net.UploadStringCompletedEventArgs instance containing the event data.

OnCalculateTruckRouteCompleted(RoutingCompletedEventArgs)

Raises the CalculateTruckRouteCompleted event to notify subscribers that a truck route calculation has finished successfully.

Declaration
protected virtual void OnCalculateTruckRouteCompleted(RoutingCompletedEventArgs e)
Parameters
RoutingCompletedEventArgs e

The event arguments containing the calculated truck routes.

OnCalculateTruckRouteError(CalculateRouteErrorEventArgs)

Raises the CalculateTruckRouteError event to notify subscribers that a truck route calculation has encountered an error.

Declaration
protected virtual void OnCalculateTruckRouteError(CalculateRouteErrorEventArgs e)
Parameters
CalculateRouteErrorEventArgs e

The event arguments containing the truck route calculation error details.

OnFileLoadAsyncComplete(String, Byte[])

Handles the completion of asynchronous file loading from cache and initiates tile download if cache content is unavailable.

Declaration
protected virtual void OnFileLoadAsyncComplete(string fileName, byte[] content)
Parameters
System.String fileName

Name of the file.
System.Byte[] content

The content.

OnInitializationComplete(EventArgs)

Raises the InitializationComplete event to notify subscribers that provider initialization has finished.

Declaration
protected virtual void OnInitializationComplete(EventArgs e)
Parameters
System.EventArgs e

The event arguments.

OnInitializationError(InitializationErrorEventArgs)

Raises the InitializationError event to notify subscribers that provider initialization has failed.

Declaration
protected virtual void OnInitializationError(InitializationErrorEventArgs e)
Parameters
InitializationErrorEventArgs e

The event arguments containing the initialization error details.

OnProviderUpdated(EventArgs)

Raises the ProviderUpdated event to notify subscribers that provider content has changed.

Declaration
protected virtual void OnProviderUpdated(EventArgs e)
Parameters
System.EventArgs e

The event arguments.

OnSearchCompleted(SearchCompletedEventArgs)

Raises the SearchCompleted event to notify subscribers that a search operation has finished successfully.

Declaration
protected virtual void OnSearchCompleted(SearchCompletedEventArgs e)
Parameters
SearchCompletedEventArgs e

The event arguments containing the search results.

OnSearchError(SearchErrorEventArgs)

Raises the SearchError event to notify subscribers that a search operation has encountered an error.

Declaration
protected virtual void OnSearchError(SearchErrorEventArgs e)
Parameters
SearchErrorEventArgs e

The event arguments containing the search error details.

OnSearchRequestCompleted(Object, DownloadStringCompletedEventArgs)

Handles the completion of search requests by processing the JSON response and extracting location information using multiple encoding strategies.

Declaration
protected virtual void OnSearchRequestCompleted(object sender, DownloadStringCompletedEventArgs e)
Parameters
System.Object sender

The sender.
System.Net.DownloadStringCompletedEventArgs e

The System.Net.DownloadStringCompletedEventArgs instance containing the event data.

OnTileDownloadComplete(Object, TileInfoEventArgs)

Handles tile download completion events, manages cache storage, and updates wraparound tiles with downloaded content.

Declaration
protected virtual void OnTileDownloadComplete(object sender, TileInfoEventArgs e)
Parameters
System.Object sender

The sender.
TileInfoEventArgs e

The TileInfoEventArgs instance containing the event data.

SearchAsync(SearchRequest)

Performs an asynchronous search operation using Bing Maps search services with the specified search request parameters.

Declaration
public void SearchAsync(SearchRequest request)
Parameters
SearchRequest request

The search request containing query text and search options.
Implements

SetView(MapViewInfo)

Sets the active map view by configuring the imagery set based on the specified view information and label settings.

Declaration
public virtual void SetView(MapViewInfo view)
Parameters
MapViewInfo view

The map view information containing the desired imagery set name and label preferences.
Implements

ViewportChanged(IMapViewport, ViewportChangeAction)

Responds to viewport changes by calculating visible tiles, managing tile downloads, and updating the tile matrix for rendering.

Declaration
public void ViewportChanged(IMapViewport viewport, ViewportChangeAction action)
Parameters
IMapViewport viewport

The current map viewport containing zoom level and visible area information.
ViewportChangeAction action

The type of viewport change that occurred.
Implements

Events

CalculateElevationCompleted

Occurs when an elevation calculation operation has completed successfully with elevation results.

Declaration
public event EventHandler<ElevationCompletedEventArgs> CalculateElevationCompleted
Event Type
System.EventHandler<ElevationCompletedEventArgs>

Implements

CalculateElevationError

Occurs when an elevation calculation operation encounters an error during execution.

Declaration
public event EventHandler<CalculateElevationErrorEventArgs> CalculateElevationError
Event Type
System.EventHandler<CalculateElevationErrorEventArgs>

Implements

CalculateRouteCompleted

Occurs when a route calculation operation has completed successfully with routing results.

Declaration
public event EventHandler<RoutingCompletedEventArgs> CalculateRouteCompleted
Event Type
System.EventHandler<RoutingCompletedEventArgs>

Implements

CalculateRouteError

Occurs when a route calculation operation encounters an error during execution.

Declaration
public event EventHandler<CalculateRouteErrorEventArgs> CalculateRouteError
Event Type
System.EventHandler<CalculateRouteErrorEventArgs>

Implements

CalculateTruckRouteCompleted

Occurs when a truck route calculation operation has completed successfully with truck routing results.

Declaration
public event EventHandler<RoutingCompletedEventArgs> CalculateTruckRouteCompleted
Event Type
System.EventHandler<RoutingCompletedEventArgs>

Implements

CalculateTruckRouteError

Occurs when a truck route calculation operation encounters an error during execution.

Declaration
public event EventHandler<CalculateRouteErrorEventArgs> CalculateTruckRouteError
Event Type
System.EventHandler<CalculateRouteErrorEventArgs>

Implements

InitializationComplete

Occurs when the Bing Maps provider has completed its initialization process and is ready for use.

Declaration
public event EventHandler InitializationComplete
Event Type
System.EventHandler

Implements

InitializationError

Occurs when provider initialization encounters an error during setup.

Declaration
public event InitializationErrorEventHandler InitializationError
Event Type
InitializationErrorEventHandler

Implements

ProviderUpdated

Occurs when the provider content has been updated with new tile data or configuration changes.

Declaration
public event EventHandler ProviderUpdated
Event Type
System.EventHandler

Implements

SearchCompleted

Occurs when a search operation has completed successfully with search results.

Declaration
public event EventHandler<SearchCompletedEventArgs> SearchCompleted
Event Type
System.EventHandler<SearchCompletedEventArgs>

Implements

SearchError

Occurs when a search operation encounters an error during execution.

Declaration
public event EventHandler<SearchErrorEventArgs> SearchError
Event Type
System.EventHandler<SearchErrorEventArgs>

Implements

Extension Methods