MAPKIT API REFERENCE

NAVBUILDER INSIDE LBS SDK

INTRODUCTION

The MapKit framework enables developers to embed a comprehensive set of location-based services that include maps, search, traffic, and static directions in an application with minimal programming effort.

The MapKit is centered on a map object that provides a tile-based solution that supports multiple layers (road map/satellite/hybrid, traffic, routes). The MapKit provides built-in controls for standard map operations such as panning and zooming using the host device's native gestures. The Map object includes programmable hooks to enable the host application to take full control of the map display.

MapKit includes a powerful Pin Manager that enables the host application to show the locations of points of interest (POI) on the map. Pins are provided with a set of standard images that can be replaced. User-defined pins can be created with individual images for maximum flexibility. A pin has an associated information bubble that is automatically displayed by MapKit when a pin is selected. The standard pin bubble graphic can be replaced a custom bubble with additional information and pictures. The Pin Manager also provides functions to zoom the view in or out to show a single pin or the entire set of pins on the map.

MapKit also provides a set of APIs to conduct complex searches that return the following types of results:

  • Address search (Geocoding)
  • Reverse Geocoding
  • Local search
  • Fuel price search
  • Movie theaters
  • Movie show times
  • Events
  • Event venues
  • Traffic incidents
  • Static route directions
  • Mobile coupons

API

The MapKit user API provides minimal low-level access to data structures associated with the map control. The reason for this is to make it easier for applications to include a full map solution with a minimum amount of work.

CONVENTIONS

Many of the APIs provided by the MapKit are asynchronous and/or have complex data structures associated with them. In order to make them as easy to use as possible, the APIs are structured as follows:

  • Request Creation functions create and initialize the data structure needed to submit and handle requests.
  • Common Request functions create, destroy, submit, retrieve, cancel and check the status of requests.
  • Information functions retrieve results and delete data structures after processing them.

PLATFORM-SPECIFIC CONSIDERATIONS

This document is intended as a general description of the MapKit API without platform considerations. The following differences will become apparent when looking at the actual implementation of the APIs for each platform:

  • Java platforms provide garbage collection, so there is no need for "destroy" functions.
  • Java requires all functions to belong to a class. This may result in slightly different grouping of methods, but function names should be similar.
  • Java and C++ use classes, so some of the parameters may not be needed as they can be retrieved from the class.
  • Brew uses C, so the function calls need additional parameters.
  • Data types are kept generic in this document, but will have specific types on the target platforms. Refer to the dynamically generated documentation for more information about platform-specific data types.

INDEX

DATA STRUCTURES

NBI_BoundingBox
A bounding box used for a search region specified by coordinates.

Name

Type

Description

point1

NBI_Coordinates

One corner of the bounding box.

point2

NBI_Coordinates

Other corner of the bounding box.

NBI_Category
A data structure used to define the category of a set of results.

Name

Type

Description

code

string

Category code.

name

string

Category name.

NBI_Context
Because some supported operating systems do not allow global variables in shared libraries, MapKit uses a context data structure to maintain all required state information. The context is an opaque data structure and should be modified only by API functions. Depending on the platform, you may need to explicitly pass the context to library functions.
NBI_Coordinates
A location on the map specified by a latitude/longitude coordinate.

Name

Type

Description

latitude

number

Latitude value.

longitude

number

Longitude value.

NBI_Event (DEPRECATED)
Event information

Name

Type

Description

contentHandle

NBI_ContentID

Used to get formatted event details.

mpaa

string

MPAA rating of the event.

name

string

Name of the event.

numberOfPerformances

number

Length of performances array.

performances

array

Array of NBI_EventPerformance objects.

stars

number

Number of stars for this event.

NBI_EventPerformance (DEPRECATED)
Event performance information

Name

Type

Description

bargainPrice

Boolean

Used to indicate bargain performances.

endTime

number

Event end time.

startTime

number

Event start time.

NBI_ExtendedPlaceData (DEPRECATED)
Extended place information.

Name

Type

Description

extendedInformation

flags

This field contains flags indicating what extended information is available. Values come from NBI_ExtendedConfiguration enumeration.

goldenCookie

object

Reserved.

overallRating

NBI_OverallRating

Overall rating of the POI.

numberOfPoiContents

number

Number of items in poiContent array.

poiContent

array

Array of NBI_POIContent structures.

poiContentID

string

Unique ID associated with this POI.

tagline

string

A merchant provided memorable slogan or teaser to attract the consumer's attention.

NBI_FuelDetails (DEPRECATED)
A type describing fuel products.

Name

Type

Description

numberOfFuelProducts

number

Number of products in the array.

fuelProduct

array

An array of NBI_FuelProduct.

NBI_FuelProduct (DEPRECATED)
A type describing a fuel product as found in various locations.

Name

Type

Description

fuelType

NBI_FuelType

Type of fuel.

price

number

Price of a fuel type at a location.

units

String

Fuel units.

NBI_FuelSummary (DEPRECATED)
Summary information for a given fuel product.

Name

Type

Description

average

NBI_FuelProduct

Average fuel price.

low

NBI_FuelProduct

Lowest fuel price.

NBI_FuelType (DEPRECATED)
A type describing information for different kinds of fuels.

Name

Type

Description

productName

string

Name of the actual fuel product as sold by providers.

typeName

string

Type of fuel regardless of the provider.

NBI_Image
A type describing an image

Name

Type

Description

data

array

Array of bytes describing the image format, which depends on platform and image type.

dataLength

number

Size of the imageData object.

type

NBI_Image_Type

Type of image.

NBI_Information
This is an opaque structure used by NBI to hold the result of a request. Special functions are provided to extract result data from the structure.
NBI_Layer
A layer is a data structure associated with a tile or POI layer in a map view. All custom layer APIs depend on a layer data structure. The layer is an opaque data structure and should be modified only by API functions. Depending on the platform, you may need to explicitly pass the layer to the library functions.
NBI_LoyaltyProgramCard
Data structure containing information about a loyalty program card.

Name

Type

Description

name

string

Name of the loyalty program card (for example: Ralphs Rewards).

number

string

Number of the loyalty program card.

NBI_MapLocation
A location contains at least a location point, but may also contain additional address fields such as street, city, state, or ZIP Code, as shown below.

Name

Type

Description

airport

string

Airport code.

freeform

string

Freeform address query.

number

string

Street number.

street

string

Street name.

street2

string

Cross-street name.

city

string

City name.

county

string

County name.

state

string

State name.

postal

string

Postal code.

country

string

Country code (ISO 3 letter country code).

areaname

string

Area name or airport name.

center

NBI_Coordinates

Coordinates of a location.

NBI_Maneuver
Data structure containing detailed information about a specific maneuver.

Name

Type

Description

maneuverID

number

Unique ID used to identify the maneuver.

primaryStreet

string

Primary street.

secondaryStreet

string

Secondary street.

description

string

String with the maneuver description.

routingIcon

string

ID of routing icon to use for the maneuver.

distance

number

Distance in kilometers from the previous maneuver.

maneuverTime

number

Time to complete this maneuver.

maneuverTrafficDelay

number

Delay due to traffic.

NBI_ManeuverList
Data structure containing all information required to display a route on a map and a list of maneuvers.

Name

Type

Description

routeID

NBI_RouteID

Route identifier that needs to be passed to the Map control to display the route overlay.

routeBoundingBox

NBI_BoundingBox

Bounding box that can be used to zoom the map to show the entire route at the best possible zoom level.

numberOfManeuvers

number

Size of the ManeuverList array.

maneuvers

array of NBI_Maneuver

Each element of the array is a NBI_Maneuver structure containing data to display the maneuver in a list.

tripTime

number

Total trip time.

tripTrafficDelay

number

Total trip delay due to traffic.

origin

NBI_Coordinates

Coordinates of the route starting point.

destination

NBI_Coordinates

Coordinates of the route destination.

NBI_Map
This is the map object. All APIs depend on a map object to work.
The map is an opaque data structure and should be modified only by API functions. Depending on the platform, you may need to explicitly pass the map to the library functions.
NBI_MapConfiguration
This is a structure to configure map object settings.

Name

Type

Description

center

NBI_Coordinates

Initial map center.

zoom

number

Initial map zoom.

viewType

NBI_MapView

Initial view type.

minimumZoomLevel

number

Minimum zoom level (must be greater than 1).

maximumZoomLevel

number

Maximum zoom level (will be clipped to the maximum supported value).

zoomInKey

char

Shortcut key used in non-touch devices to zoom in the map (default is Q).

zoomOutKey

char

Shortcut key used in non-touch devices to zoom out the map (default is P).

previousKey

char

Shortcut key used in non-touch devices to select the previous POI (default is 1)

nextKey

char

Shortcut key used in non-touch devices to select the next POI (default is 3).

enableZoomButtons

Boolean

Enable the display of the zoom in and out buttons.

enableTrafficButton

Boolean

Enable the display of the traffic on/off.

enableLocateMeButton

Boolean

Enable the display of the Locate Me button.

place

NBI_Place

An initial place to use for initializing the map. A pin is added at this location if specified.

forceTileSize256

Boolean

Should be set to true if using a custom layer that does not specify a tile size and uses a fixed 256 tile size.

NBI_MobileCoupon (DEPRECATED)
Data structure containing information about a mobile coupon.
Name
Type
Description

availability

array

Availability of this coupon (local, national,e-commerce).

numberOfAvailability

number

Count of items in the array.

acquisition

array

How does the user acquire the deal associated with the coupon (in store, printout, etc).

numberOfAcquisition

number

Count of items in the array.

title

string

Title of coupon (short description).

description

string

Long description of coupon.

conditions

string

Conditions (if any) for the coupon.

id

string

Unique ID of the coupon (provided by CSP).

startDate

NBI_LocalTime

Date from which the coupon is valid.

expirationDate

NBI_LocalTime

Expiration date of the coupon.

discountType

number

0:unspecified
1:amount
2:percentage

buyValue

number

The actual money being paid for the deal. Unused if discountPercentage is true.

discountValue

number

Value of the discount (discountType=1) or percentage amount (discountType=2). Unused if discountType=0.

listValue

number

The cost the user would pay without the discount. Unused if discountPercentage is true.

couponCode

string

If the coupon has a code that can be redeemed by typing it in, this field contains the code. This is not used with the mPhoria API, but is specified for future compatibility.

imageURL

string

If the coupon has an image to display, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

smallThumbURL

string

If the coupon has a small displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

mediumThumbURL

string

If the coupon has a medium displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

largeThumbURL

string

If the coupon has a large displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

redeemBy

NBI_CouponRedeemType

Notification to the user that the coupon is redeemed.
Note
: The first release of the version only supports NBI_CouponRedeemByURL so the value of this field is currently constant for all mobile coupons.

NBI_OverallRating
Contains the overall rating of a POI

Name

Type

Description

averageRating

number

Average rating.

ratingCount

number

Number of ratings.

NBI_Phone
A structure containing a phone number and its type.

Name

Type

Description

type

NBI_PhoneType

Type of phone.

country

number

Country code.

area

number

Area code.

number

number

Actual phone number.

NBI_Pin
A pin contains place information. Some additional fields are used by the pin manager such as pin type and pin image. Only pins of type NBI_PINTYPE_CUSTOM_IMAGE are allowed to specify the pinImage field, all other types will auto-fill this object to predefined standard images.

Name

Type

Description

type

NBI_PinType

Pin type.

line1

string

First line of text. Defaults to place name.

line2

string

Second Line of text. Defaults to place address.

place

NBI_Place

Place information for the pin.

pinImage

NBI_PinImage

Pin image. Only allowed when pin type is NBI_PIN TYPE_CUSTOM_IMAGE.

userData

void*

Pointer to arbitrary user data that can be set by the application to associate arbitrary data with each pin.

NBI_PinImage
A pin image contains an image type tag and a pointer to the image data.

Name

Type

Description

tipx

number

x coordinate of pin image tip relative to the image top left.

tipy

number

y coordinate of pin image tip relative to the image top left.

bubblex

number

x coordinate of bubble tip inside the pin image, with 0 the leftmost pixel.

bubbley

number

y coordinate of bubble tip inside the pin image, with 0 the topmost pixel.

image

pointer

A pointer to the image data.

imageDataSize

number

The size of the image data.

NBI_Place
A place contains a location plus additional fields such as location name and other details.

Name

Type

Description

name

string

Name of place.

location

NBI_MapLocation

Place location.

categories

array

Array of NBI_Category.

phones

array

Array of NBI_Phone.

NBI_POIContent (DEPRECATED)
This structure is a key/value pair that provides additional formatted information for a POI.

Name

Type

Description

key

string

Name of the content.

value

string

Value of the content.

NBI_Rectangle
This structure is a rectangle defined by 4 coordinates in the screen's coordinate system.

Name

Type

Description

top

number

Top of the rectangle.

left

number

Left side of the rectangle.

bottom

number

Bottom of the rectangle.

right

number

Right side of the rectangle.

NBI_Request
The request is an opaque data structure and should be modified only by API functions. Requests are used to interact with the NavBuilder server to submit queries and receive results. Depending on the platform, you may need to explicitly pass the request to the library functions.
NBI_RouteID
ID used to identify a requested route on the server.

Name

Type

Description

data

array of bytes

Route ID string.

size

number

Size of the data array.

NBI_RouteOptions
User routing options.

Name

Type

Description

avoid

flags

Created by OR'ing the values in NBI_RouteAvoid enumeration.

transportationMode

NBI_TransportationMode

Transportation mode (car, pedestrian, truck, bicycle).

routeType

NBI_NavRouteType

Route Type (fastest, shortest, or simplest).

NBI_SearchFilter
The NBI_SearchFilter object is an opaque object that holds an arbitrary number of key-value pairs added by using NBI_AddKeyValuePair. The object can then be passed to functions that take this type of parameter.  The NBI_SearchFilter object can be deleted using NBI_DeleteKeyValuePair.
NBI_SearchRegion
Search region.

Name

Type

Description

boundingBox

NBI_BoundingBox

Bounding box for search. This search type is currently not supported for any search type and should not be used. Only center can be used in the current NBI Map Kit release.

center

NBI_Coordinates

Center point of the search region.

type

NBI_SearchRegionType

Type of search.

NBI_Store
Data structure containing an information about retailer's store.

Name

Type

Description

place

NBI_Place

Retailer's place information. Can be empty for a coupon search returning deals.

Name

string

Retailer's name.

id

string

Unique ID for retailer, on CSP system.

broadCategory

array

Broad categories associated with this retailer.

numberOfBroadCategories

number

Number of broad categories.

category

array

Categories associated with this retailer.

numberOfCategories

number

Number of categories.

subcategory

array

Sub-categories associated with this retailer.

numberOfSubCategories

number

Number of sub-categories.

couponCount

number

Number of coupons found that meet the query filters.

imageURL

string

If the store has an image to display, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

smallThumbURL

string

If the store has a small displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

mediumThumbURL

string

If the store has a medium displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

largeThumbURL

string

If the store has a large displayable thumb image, then its URL is provided here; in order to be loaded/displayed on the client, it must also be loaded using NBI_GetImageRequestCreate 2.14.1.9.

NBI_StoreCoupons
Data structure containing information about a store and zero or more associated coupons.

Name

Type

Description

store

NBI_Store

Store that the coupons are associated with.

coupons

array

Array of coupons (NBI_MobileCoupon) associated with the store.

numberOfCoupons

number

Number of coupons.

NBI_SummaryResult
Summary results of a POI search.

Name

Type

Description

category

NBI_Category

NBI_Category structure containing the category of results.

count

number

Number of results.

time

number

Time.

NBI_TrafficIncident
A type describing a traffic incident.

Name

Type

Description

description

string

Traffic incident description.

endTime

time

Time at which the incident was cleared from the street.

entryTime

time

Time when the incident was entered into the database.

severity

NBI_TrafficIncidentSeverity

Severity of an accident.

startTime

time

Time when an accident occurred.

type

NBI_TrafficIncidentType

Type of accident.

road

string

String describing the road where the incident occurred.

NBI_WeatherConditions
Data structure containing weather conditions.

Name

Type

Description

ceiling

number

 

condition

string

 

conditionCode

number

 

dewPoint

number

 

heatIndex

number

 

maximumTemperature24Hours

number

Maximum temperature in the next 24 hours.

maximumTemperature6Hours

number

Maximum temperature in the next 6 hours.

minimum Temperature24Hours

number

Minimum temperature in the next 24 hours.

minimum Temperature6Hours

number

Minimum temperature in the next 6 hours.

precipitation24Hours

number

Precipitation in a 24 hour period.

precipitation3Hours

number

Precipitation in a 3 hour period.

precipitation6Hours

number

Precipitation in a 6 hour period.

pressure

number

Pressure value in ?

relativeHumidity

number

Humidity value in ?

skyConditions

string

 

snowDepth

number

 

temperature

number

Current temperature.

updateTime

NBI_LocalTime

Time when this information was gathered.

UTCOffset

number

Offset time values by this amount.

visibility

number

Road visibility information.

windChill

number

 

windDirection

number

Wind direction.

windGust

number

 

windSpeed

number

Wind speed in ?

NBI_WeatherForecast
Data structure containing a weather forecast.

Name

Type

Description

condition

string

Weather condition.

conditionCode

number

 

date

number

Date of a weather forecast.

dayNumber

number

Unused.

highTemperature

number

Forecasted high temperature.

lowTemperature

number

Forecasted low temperature.

moonPhase

number

 

moonrise

string

 

moonset

string

 

precipitationProbability

number

Forecasted precipitation probability.

relativeHumidity

number

Forecasted humidity.

sunrise

string

Forecasted sunrise.

sunset

string

 

updateTime

number

Time when a forecast was produced.

UTCOffset

number

Offset time values by this amount.

UVDescription

string

 

UVIndex

number

 

windDirections

number

Forecasted wind direction.

windSpeed

number

Forecasted wind speed.

NBI_WeatherForecasts
Data structure containing an array of weather forecasts.

Name

Type

Description

numberOfForecasts

number

Number of items in the array.

weatherForecasts

array

Array of NBI_WeatherForecast.

Data Types
The following data types are used by the MK API as needed.

Name

Type

Description

NBI_Color

number

Unsigned 32 bit number containing 8bits or R-G-B-Alpha.

NBI_Error

number

Error code (see appendix for current list).

NBI_EventRating

enumeration

NBI_ER_All 
NBI_ER_KidFriendly 

NBI_Font

enumeration

NBI_Font_Normal 
NBI_Font_Bold 
NBI_Font_Large 
NBI_Font_Large_Bold 

NBI_FuelSearchType

enumeration

NBI_FST_Regular 
NBI_FST_Diesel 
NBI_FST_Ehanol85 

NBI_ImageType

enumeration

NBI_ImageType_PNG 
NBI_ImageType_JPEG 
NBI_ImageType_BMP 

NBI_IncidentSeverity

enumeration

NBI_IncidentSeverity_NoIncident 
NBI_IncidentSeverity_Severe 
NBI_IncidentSeverity_Major 
NBI_IncidentSeverity_Minor 
NBI_IncidentSeverity_LowImpact

NBI_IncidentType

enumeration

NBI_IncidentType_Accident 
NBI_IncidentType_Congestion 
NBI_IncidentType_DisabledVehicle 
NBI_IncidentType_RoadHazard 
NBI_IncidentType_UnscheduledConstruction 
NBI_IncidentType_ScheduledConstruction 
NBI_IncidentType_PlannedEvent 
NBI_IncidentType_MassTransit 
NBI_IncidentType_OtherNews 
NBI_IncidentType_MiscEvent

NBI_IterationCommand

enumeration

NBI_IterationCommand_Next 
NBI_IterationCommand_previous

NBI_LayerType

enumeration

NBI_LayerType_Base 
NBI_LayerType_Overlay 
NBI_LayerType_Overlay_With_Labels 
NBI_LayerType_POI 
NBI_LayerType_Pin

NBI_LocalTime

number

Time in seconds since January 6, 1980, in the local time zone.

NBI_MapLocation

object

Location data.

NBI_Map

object

Map instance object.

NBI_MapView

enumeration

NBI_MAPVIEW_Invalid 
NBI_MAPVIEW_Road 
NBI_MAPVIEW_Satellite 
NBI_MAPVIEW_Hybrid

NBI_MovieShowing

enumeration

NBI_MS_NowInTheaters 
NBI_MS_TopBoxOffice 
NBI_MS_OpeningThisWeek 
NBI_MS_ComingSoon 
NBI_MS_SpecificTime 

NBI_MovieSortBy

enumeration

NBI_MSB_MostPopular 
NBI_MSB_MostRecent 
NBI_MSB_Alphabetical 

NBI_PhoneType

enumeration

NBI_Phone_Primary 
NBI_Phone_Secondary 
NBI_Phone_National 
NBI_Phone_Mobile 
NBI_Phone_Fax 

NBI_Pin

object

An object that visually represents a place on the map.

NBI_PinImage

object

An object that encapsulates an image type and its data structure.

NBI_PinType

enumeration

NBI_PINTYPE_RED: a red pin 
NBI_PINTYPE_BLUE: a blue pin 
NBI_PINTYPE_GREEN: a green pin 
NBI_PINTYPE_YELLOW: a yellow pin 
NBI_PINTYPE_ORANGE: an orange pin
NBI_PINTYPE_START_FLAG: start of a route flag 
NBI_PINTYPE_DESTINATION_FLAG: end of route flag
NBI_PINTYPE_CUSTOM_IMAGE: a pin with a custom image 

NBI_Place

object

A named location with optional category and phone number(s).

NBI_POIExtendedConfiguration

enumeration

NBI_PEC_None
NBI_PEC_EnhancedPOI 
NBI_PEC_FormattedText 

NBI_RouteAvoid

enumeration (to be used as bit flags)

NBI_RouteAvoidHOV = 1 
NBI_RouteAvoidToll = 2 
NBI_RouteAvoidHighway = 4 
NBI_RouteAvoidUTurn = 8

NBI_RouteType

enumeration

NBI_NRT_Easiest 
NBI_NRT_Fastest 
NBI_NRT_Shortest

NBI_SearchRegionType

enumeration

NBI_ST_None 
NBI_ST_Center 
NBI_ST_BoundingBox 

NBI_InformationResultType

enumeration

NBI_SRT_None 
NBI_SRT_SubSearch 
NBI_SRT_Place 
NBI_SRT_Events 
NBI_SRT_EventSummary 
NBI_SRT_FuelDetails 
NBI_SRT_FuelSummary 
NBI_SRT_Location 
NBI_SRT_ManeuverList 
NBI_SRT_Weather
NBI_SRT_MC_Enroll 
NBI_SRT_MC_Unenroll 
NBI_SRT_MC_ClipCoupon 
NBI_SRT_MC_MoveClipping 
NBI_SRT_MC_LoyaltyCard 
NBI_SRT_MC_MobileCoupon 
NBI_SRT_MC_StoreCoupons

NBI_SearchType

enumeration

NBI_ST_Default 
NBI_ST_Fuel 

NBI_TransportationMode

enumeration

NBI_TransportationModeCar 
NBI_TransportationModeTruck 
NBI_TransportationModeBicycle 
NBI_TransportationModePedestrian 

NBI_TrafficIncidentSeverity

enumeration

NBI_TrafficIncidentSeverityCritical 
NBI_TrafficIncidentSeverityMajor 
NBI_TrafficIncidentSeverityMinor 
NBI_TrafficIncidentSeverityLowImpact

NBI_TrafficIncidentType

enumeration

NBI_TrafficIncidentTypeAccident 
NBI_TrafficIncidentTypeCongestion 
NBI_TrafficIncidentTypeDisabledVehicle 
NBI_TrafficIncidentTypeRoadHazard 
NBI_TrafficIncidentTypeUnscheduledConstruction 
NBI_TrafficIncidentTypeScheduledConstruction 
NBI_TrafficIncidentTypePlannedEvent 
NBI_TrafficIncidentTypeMassTransit 
NBI_TrafficIncidentTypeOtherNews 
NBI_TrafficIncidentTypeMisc

NBI_DiscountThresholdType

enumeration

NBI_DiscountThresholdType_Amount 
NBI_DiscountThresholdType_Percentage

NBI_ClippingStatus

enumeration

NBI_ClippingStatus_Pending 
NBI_ClippingStatus_Expired 
NBI_ClippingStatus_Invalid 
NBI_ClippingStatus_Redeemed 
NBI_ClippingStatus_Unknown

NBI_CouponRedeemType

enumeration

NBI_CouponRedeemByURL 
NBI_CouponRedeemByClip 
NBI_CouponRedeemByDisplay 
NBI_CouponRedeemByUnknown

NBI_CouponAnalyticsEvent

enumeration

NBI_CouponAnalyticsEvent_Display 
NBI_CouponAnalyticsEvent_URL 
NBI_CouponAnalyticsEvent_ViewDetails 
NBI_CouponAnalyticsEvent_Call 
NBI_CouponAnalyticsEvent_Navigate

CONTEXT FUNCTIONS

Context Functions

Context APIs enable an application to create and manage a MapKit context.

NBI_ContextCreate 

NBI_ContextDestroy 

NBI_ContextGetAPILevel

NBI_ContextResetCaches

NBI_ContextCreate

The NBI_ContextCreate call initializes a new context for MapKit.

NBI_Error NBI_ContextCreate (
  char * token,
  char * languageCode, 
  NBI_Context** context )

Type

Name

Description

char*

token

Credential used to authenticate the app as a valid user. Tokens can be obtained by signing up for a VDC account and requesting a token at the NBI section in the VDC website.

char*

languageCode

String representing the desired language according to the RFC1766 specification (en-US and es-US are supported).

NBI_Context**

context

Context is an opaque structure used by NBI to maintain all its state variables.

Possible return values:
  • NBI_SUCCESS: successful call, an initialized context is returned in context.
  • NBI_ERROR.
NBI_ContextDestroy

The NBI_ContextDestroy call releases the memory allocated by the NBI_Context data structure.

NBI_Error NBI_ContextDestroy(NBI_Context * context)

Type

Name

Description

NBI_Context*

context

The context is an opaque structure used by NBI to maintain all its state variables.

Possible return values:
  • NBI_SUCCESS: successful call, context is released
  • NBI_ERROR:
NBI_ContextGetAPILevel

The NBI_ContextGetAPILevel function returns a number representing the supported API level for the version of NBI context being used. Each time a release adds or changes functionality, the API level increments by 1. NBI guarantees compatibility for applications written for a lower API level, but not higher.

int ContextGetAPILevel ( 

  NBI_Context* context )

Type

Name

Description

NBI_Context*

context

The NBI context structure that was created with NBI_ContextCreate().

Possible return values:
  • <API level> an integer representing the API level of the NBI libraries being used.
NBI_ContextResetCaches

The NBI_ContextResetCaches function provides a means to delete caches maintained by NBI. The function enables individual caches to be reset by setting the appropriate parameters.

int NBI_ContextResetCaches(
  NBI_Context *context,
  boolean resetLocalTilesCache,
  boolean resetSharedTilesCache,
  boolean resetLocationCache
)

Type

Name

Description

NBI_Context*

context

The NBI context structure that was created with NBI_ContextCreate().

boolean

resetLocalTilesCache

Reset the local tile cache. Depending on the application usage, this may or may not result in something being deleted.

boolean

resetSharedTilesCache

Reset the shared tile cache. If the service application is not present, the local tile storage for non-custom tiles is deleted.

boolean

resetLocationCache

Reset the location cache. If the service application is not available, the local location cache is reset.

Possible return values:
  • SUCCESS: the requested caches have been reset.

MAP CONTROL

The Map Control APIs enables an application to create and manage a map view. UI events are handled by the Map Control code as transparently as possible, but depending on the OS, events may need to be explicitly passed to the Map by the host application.

NBI_MapCreate
NBI_MapDefaultConfigurationFromLocation
NBI_MapDefaultConfigurationFromPlace

NBI_MapGetCenter
NBI_MapGetZoomLevelRange
NBI_MapGetSize
NBI_MapGetZoomLevel
NBI_MapIsAnimating

NBI_MapSetCenter
NBI_MapSetCenterAndZoomLevel
NBI_MapSetSize
NBI_MapSetZoomLevel
NBI_MapZoomToBoundingBox

NBI_MapCreate

The NBI_MapCreate function allocates a new map object and initializes its data.

NBI_Error NBI_MapCreate (
  NBI_Context* context ,
  NBI_MapConfiguration* configuration , 
  NBI_View* parentView , 
  NBI_Map** map )

Type

Name

Description

NBI_Context*

context

The context is an opaque structure used by NBI to maintain all its state variables.

NBI_MapConfiguration*

configuration

Pointer to a NBI_MapConfiguration structure containing the initial settings for the map.

NBI_View*

parentView

View that will contain this map instance. The Map will be sized to occupy the entire parent window.
Note: this is a placeholder data structure that will be replaced with a similar platform-dependent structure.

NBI_Map**

map

map is where the newly created object will be returned. This object will be needed to communicate with the map functions in all remaining APIs.

NBI_MapDefaultConfigurationFromLocation

The NBI_MapDefaultConfigurationFromLocation call initializes an NBI_MapConfiguration with the data required to show a location on a map. Call NBI_MapCreate with this configuration to show a map centered at the location.

Note: Use NBI_MapDefaultConfigurationFromPlace to initialize a map and add a pin in the specified location.

NBI_Error NBI_MapDefaultConfigurationFromLocation (
  NBI_Location* location , 
  NBI_MapConfiguration* configuration )

Type

Name

Description

NBI_Location*

location

The map will be centered at the coordinates specified at this location.

NBI_MapConfiguration*

configuration

Use this configuration with NBI_MapCreate to initialize a map that will follow the device's position. The caller is responsible for allocating/releasing the NBI_MapConfiguration structure.

Possible return values:
  • NBI_SUCCESS: successful call, configuration contains the data needed to initialize a map.
  • NBI_ERROR_BAD_PARAMETER: one or more of the parameters are invalid.
NBI_MapDefaultConfigurationFromPlace

The NBI_MapDefaultConfigurationFromPlace call initializes an NBI_MapConfiguration with the data required to show a place on a map. Call NBI_MapCreate with this configuration to show a map centered at the place with a pin on it.

NBI_Error NBI_MapDefaultConfigurationFromPlace(
  NBI_Place* place,
  NBI_MapConfiguration* configuration)

Type

Name

Description

NBI_Place*

place

The place that will be used to define the center of the map and to populate and add a pin when initializing it using the returned configuration.

NBI_MapConfiguration*

configuration

Use this configuration with NBI_MapCreate to initialize a map that will follow the device's position. The caller is responsible for allocating/releasing the NBI_MapConfiguration structure.

Possible return values:
  • NBI_SUCCESS: successful call, configuration contains the data needed to initialize a map.
  • NBI_ERROR_BAD_PARAMETER: one or more of the parameters are invalid.
NBI_MapGetCenter

The NBI_MapGetCenter call returns the map center coordinates in the center parameter. The function return value is an error code or NBI_SUCCESS if the function call succeeded.

NBI_Error NBI_MapGetCenter(NBI_Map* map, NBI_Coordinates* center)

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all the state information needed to interact with the map control.

NBI_Coordinates*

center

Output parameter that will contain the current map center.

Possible return values:
  • NBI_SUCCESS: successful call, lat/lon contain the coordinates of the current map center.
  • NBI_ERROR_UNINITIALIZED_MAP: the map object has not been initialized.
NBI_MapGetZoomLevelRange

The NBI_MapGetZoomLevelRange call returns the minimum and maximum map zoom levels.

Zoom levels start at 1 or 2 (depending on the device screen size), which is the lowest zoom level and shows the US View. Each zoom step increases the map magnification by a factor of 2. A map is divided into 2**zoomLevel tiles in both X and Y directions. The maximum zoom level is provided by the server, which can be updated to support additional zoom levels in the future.

NBI_Error NBI_MapGetZoomLevelRange(NBI_Map* map,
  int* minimumZoomLevel,
  int* maximumZoomLevel )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int*

minimumZoomLevel

Output parameter that contains the current map's minimum zoom level.

int*

maximumZoomLevel

Output parameter that contains the current map's maximum zoom level.

Possible return values:
  • NBI_SUCCESS: successful call. The maximum zoom level for the map is copied to maximumZoomLevel.
  • NBI_ERROR_INVALID_PARAMETER: one or more of the parameters are NULL.
NBI_MapGetSize

The NBI_MapGetSize function returns the current map size in the local view's coordinates.

Note: depending on the platform, this function may not be needed, as the map may inherit the size of its parent view.

NBI_Error NBI_MapGetSize (
  NBI_Map* map , 
  width , 
  height )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Int*

width,height

Output parameters containing the current size of the map in the local view coordinate system.

Possible return values:
  • NBI_SUCCESS: successful call, the map size is returned in the parameters.
  • NBI_ERROR_BAD_PARAMETER: error, one or more of the parameters is NULL.
NBI_MapGetZoomLevel

The NBI_MapGetZoomLevel call returns the current map zoom level. The function return value is the zoom level or NBI_ERROR_MAP_NOT_INITIALIZED if the map has not been initialized. 

Zoom levels start at 0, which is the lowest zoom level and shows the entire U.Ss View. Each zoom step increases map magnification by a factor of 2. The map is divided into 2**zoomLevel tiles in both X and Y directions. The maximum zoom level is NBI_MAX_ZOOM_LEVEL, but this number is not fixed because the server can be updated to support additional zoom levels.

NBI_Error NBI_MapGetZoomLevel ( NBI_Map* map, int* zoomLevel )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int*

zoomLevel

Output parameter that contains the current map zoom level.

Possible return values:
  • NBI_SUCCESS: successful call. The current zoom level is copied to zoomLevel.
  • NBI_ERROR_INVALID_PARAMETER: one or more of the parameters are NULL.
NBI_MapIsAnimating

The NBI_MapIsAnimating call is used to determine if the map is currently animated. This function can be used to prevent animations from being stopped, for example when the map is panning to a new location or when the zoom keys are used. If the function returns TRUE, an application action can be delayed before issuing a new command.

boolean NBI_MapIsAnimating(NBI_Map* map)

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • TRUE: the map is performing an animation.
  • FALSE: the map is not animating.
NBI_MapSetCenter

The NBI_MapSetCenter function changes the map center to the requested NBI_Coordinates. If animate is true, and the map's new center is less than a screen away (in width or height), then the movement to the new center is done using an animated pan. If animate is false or the distance to the new center is larger than a full screen, then the map is redrawn at the new location. The function return value is an error code or NBI_SUCCESS if the function call succeeds.

NBI_Error NBI_MapSetCenter (
  NBI_Map* map , 
  NBI_Coordinates* center , 
  boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates*

center

Target coordinate of the new map center.

Boolean

animate

If true, the transition to the new center is animated.

Possible return values:
  • NBI_SUCCESS: successful call, lat/lon contain the coordinates of the current map center.
  • NBI_ERROR_INVALID_LOC: the requested center is not a valid coordinate pair.
NBI_MapSetCenterAndZoomLevel

The NBI_MapSetCenterAndZoomLevel function sets both the center and the zoom level of the map. 

Zoom levels start at 0, which is the lowest zoom level and shows the U.S. View Each zoom step increases the map magnification by a factor of 2. The map is divided into 2**zoomLevel tiles in both X and Y directions. The maximum zoom level is NBI_MAX_ZOOM_LEVEL, but this number is not fixed because the server can be updated to support additional zoom levels. The host application can request any zoom level (as newer higher levels of zoom may become available in the future), but if the level is not available, the function sets the zoom to the closest available zoom level. 

If the new center is not a valid location, then the call is ignored. 

If the animate parameter is true, the map control performs an animation to the new zoom level. 

Note: The only difference between using this function call instead of calling NBI_MapSetCenter(map,center) followed by NBI_MapSetZoomLevel(map,zoomLevel) is that only one redraw will happen as opposed to two.

NBI_Error NBI_MapSetCenterAndZoomLevel (
  NBI_Map* map , 
  NBI_Coordinates* center , 
  int* zoomLevel , 
  Boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates*

center

Target coordinate of the new map center.

int*

zoomLevel

Requested new zoom level. On success, the parameter is updated to the new zoom level, which may be the different from the one requested if the requested zoom level is not supported.

Boolean

animate

If true, the transition is animated.

Possible return values:
  • NBI_SUCCESS: the map center and zoom are changed, and the new zoom level is copied to the zoomLevel parameter.
  • NBI_ERROR_INVALID_LOC: the requested center is not a valid coordinate pair.
  • NBI_ERROR_INVALID_PARAMETER: one or more of the parameters are NULL.
NBI_MapSetSize

The NBI_MapSetSize function changes the map view rectangle to the requested size. The size of the new rectangle must fit within its enclosing window. This function can be used to show a smaller map within a larger view.

Note: depending on the platform, this function may not be needed, as the map may be enclosed in a view that provides sizing.

NBI_Error NBI_MapSetSize (
  NBI_Map* map , 
  int width , 
  int height )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

width,height

Parameters containing the desired size of the map in the local view coordinate system.

Possible return values:
  • NBI_SUCCESS: successful call, the map is resized to the requested values.
  • NBI_ERROR_INVALID_SIZE: one or more of the values cause the map to no longer fit within its parent view.
NBI_MapSetZoomLevel

The NBI_MapSetZoomLevel function controls the zoom level of the map.

Zoom levels start at 0, which is the lowest zoom level and shows the U.S. View. Each zoom step increases the map magnification by a factor of 2. The map is divided into 2**zoomLevel tiles in both X and Y directions. The maximum zoom level is NBI_MAX_ZOOM_LEVEL, but this number is not fixed because the server can be updated to support additional zoom levels. The host application can request any zoom level (as newer higher levels of zoom may become available in the future), but if the level is not available, the function sets the zoom to the closest available zoom level.

If the animate parameter is true, the map control performs an animation to the new zoom level.

NBI_Error NBI_MapSetZoomLevel (
  NBI_Map* map , 
  int zoomLevel , 
  boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

zoomLevel

Requested new zoom level. On success, the parameter is updated to the new zoom level, which can be the different if the requested zoom level is not supported.

boolean

animate

If true, the transition to the new center is animated.

Possible return values:
  • NBI_SUCCESS: successful call. The current zoom level is copied to zoomLevel.
  • NBI_ERROR_INVALID_PARAMETER: one or more of the parameters are NULL.
NBI_MapZoomToBoundingBox

The NBI_MapZoomToBoundingBox function uses two input coordinate points to form a rectangular bounding box and calculates the map size and zoom that best fits that bounding box (including some padding to make sure that pins being shown are not cut off).

The map position is updated to place the requested bounding box at the center of the actual bounding box. The return value is the new zoom level.

If the animate parameter is true, the map control performs an animation to the new zoom level.

NBI_Error NBI_MapZoomToBoundingBox (
  NBI_Map* map , 
  NBI_Coordinates* point1 , 
  NBI_Coordinates* point2 , 
  Int * zoomLevel , 
  boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates*

point1

One of the corners of the bounding box.

NBI_Coordinates*

point2

The other coordinate of the bounding box.

int

zoomLevel

Requested new zoom level.

Boolean

animate

If true, the transition is animated.

Possible return values:
  • New zoom level.
  • NBI_SUCCESS: the map center and zoom are changed and the new zoom level is copied to the zoomLevel parameter.
  • NBI_ERROR_INVALID_LOC: at least one of the requested coordinates is not a valid coordinate pair.
  • NBI_ERROR_INVALID_PARAMETER: one or more of the parameters are NULL.

MAP CONTROL EVENT MANAGEMENT

The following sections describe the APIs to pass events to the map control and register with the map control to receive event notifications.

MAP CONTROL EVENT MANAGEMENT - PASSING EVENTS

Depending on the platform, the host application may be required to pass all events to the map control, or they may be automatically handled. Check with the specific platform for instructions on how to use these function calls.

NBI_MapHandleEvent 

NBI_MapHandleEvent

The NBI_MapHandleEvent function takes as input an event and returns a status code that allows the host application to determine if the event was handled.

NBI_Error NBI_MapHandleEvent ( NBI_Map* map, NBI_Event* Event )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Event*

event

Structure containing the event information (platform-specific).

Possible return values:
  • NBI_SUCCESS: the event was handled by the map control.
  • NBI_ERROR_EVENT_NOT_HANDLED: the event was ignored.
MAP CONTROL EVENT MANAGEMENT - REGISTERING FOR EVENTS
NBI_MapBeginUserEventCallback

The NBI_MapBeginUserEventCallback function enables the application to intercept user events. The application can process the event and notify the map that it has been handled. If the application handles the event, it must set *endMsg to non-zero. The *endMsg value set by the application is used as the msg parameter to the NBI_MapEndUserEventCallback callback. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapBeginUserEventCallback ) (
  void* appData , 
  NBI_Map* map , 
  NBI_PlatformEvent* event );

Type

Name

Description

void*

appData

Context data passed by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_PlatformEvent*

event

Platform-specific event structure containing event data.

NBI_Error NBI_MapSetBeginUserEventCallback (
  NBI_Map* map ,
  NBI_MapBeginUserEventCallback callback ,
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapBeginUserEventCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapEndUserEventCallback

The NBI_MapEndUserEventCallback function allows the application to record user events. Recorded events can be played back later for testing or debugging. This callback is made after the event is processed, so that mouse-up/down/move messages that are converted to a drop-pin event can be recorded correctly. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapEndUserEventCallback ) (
  void* appData , 
  NBI_Map* map ,
  NBI_PlatformEvent* event );

Type

Name

Description

void*

appData

Context data passed by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

boolean

handled

Non-zero if the map handles the event.

NBI_PlatformEvent*

event

A platform-specific event structure containing event data.

NBI_Error NBI_MapSetEndUserEventCallback (
  NBI_Map* map , 
  NBI_MapEndUserEventCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapEndUserEventCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetCenterAndZoomChangeCallback

The NBI_MapSetCenterAndZoomChangeCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the map center and/or zoom level are changed. If called due to an animation, the callback is called twice, once at the beginning of the animation with the animating parameter set to true and once at the end of the animation with the animating parameter set to false. In both cases, the end values are passed for lat/lon/newZoom. To disable the callback, call the function with a NULL pointer.

Note: This callback may be called while the map is being resized during an animation, so it is extremely time-sensitive. If you use it during a map animation, you should make sure it returns very quickly or it may affect animation performance.

typedef void (CALLBACK* NBI_MapCenterAndZoomChangeCallback ) (
  void* appData , 
  NBI_Map* map , 
  double lat , 
  double lon , 
  double newZoom , 
  int animating , 
  int byUserAction );

NBI_Error NBI_MapSetCenterAndZoomChangeCallback (
  NBI_Map* map , 
  NBI_MapCenterAndZoomChangeCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapCenterAndZoomChangeCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetDropPinCallback

The NBI_MapSetDropPinCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the map detects a press and hold gesture to drop a pin.

The callback function provides the host application with a control to allow or disallow the pin drop operation.

Note: the callback is only triggered by the press and hold event. Dropping a pin algorithmically using NBI_MapDropPin is under the control of the host application and it does not need confirmation.

To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapDropPinCallback ) (
  void* appData , 
  NBI_Map* map , 
  int x , 
  int y ,
  int* allow);

Type

Name

Description

void*

appData

Context data passed from the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x, y

Coordinates of the pin in the coordinate system of the map view.

int*

allow

Set this variable to FALSE to prevent a pin from being dropped.

NBI_Error NBI_MapSetDropPinCallback(
  NBI_Map* map ,
  NBI_MapDropPinCallback callback ,
  void* appData)

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapDropPinCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetDroppedPinCallback

The NBI_MapSetDroppedPinCallback function takes as input a function pointer and a pointer to app-provided data and calls the function after a pin has been dropped on a map to provide the pin ID and location. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapDroppedPinCallback) (
  void* appData ,
  NBI_Map* map ,
  int x ,
  int y ,
  int pinID );

Type

Name

Description

void*

appData

Context data passed by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x, y

Coordinates of the pin in the coordinate system of the map view.

int

pinID

ID of the pin that was dropped on the map.

NBI_Error NBI_MapSetDroppedPinCallback(
  NBI_Map * map ,
  NBI_MapDropPinCallback callback ,
  void *appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapDroppedPinCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPaintCallback

The NBI_MapSetPaintCallback function takes as input a function pointer and a pointer to application-provided data and calls the function after the map has painted its off-screen bitmap. The application can add its own text/graphics on top of the map in a flicker-free manner.

After this callback returns, the map copies the bitmap to its window. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapPaintCallback) (
  void* appData , 
  NBI_Map* map , 
  HDC hdc , 
  RECT hdcRect , 
  RECT clipRect );

NBI_Error NBI_MapSetPaintCallback (
  NBI_Map* map , 
  NBI_MapPaintCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapSetPaintCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinBubbleGetRectangleCallback

The NBI_MapSetPinBubbleGetRectangleCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the Pin Manager needs to obtain the rectangle information for a custom pin. To disable the callback, call the function with a NULL pointer.

The Pin Manager calls this function whenever it needs to draw a pin’s bubble to calculate the position and decide if the map needs to move. If the application wants to implement a custom bubble, it should set the returned rectangle to the area it needs to draw it. If the app wants to use a standard pin bubble drawn by the Pin Manager, it should return false in the callback.

typedef boolean (CALLBACK* NBI_MapPinBubbleGetRectangleCallback) (
  void* appData ,
  NBI_Map* map ,
  int PinID ,
  int x ,
  int y ,
  NBI_Rectangle* bubbleRectangle);

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

PinID

ID of the pin being queried for its bubble's rectangle.

int

x, y

Coordinates of the pin in the screen's coordinate system.

NBI_Rectangle*

bubbleRectangle

Rectangle for the pin's bubble.

NBI_Error NBI_MapSetPinBubbleGetRectangleCallback(
  NBI_Map* map ,
  NBI_MapPinBubbleGetRectangleCallback callback,
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinBubbleGetRectangleCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinBubbleDrawCallback

The NBI_MapSetPinBubbleDrawCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the Pin Manager wants the host application to draw a custom pin bubble. To disable the callback, call the function with a NULL pointer.

The Pin Manager calls this function only if the NBI_MapPinBubbleGetRectangleCallback was called for the selected pin and it returned true with a valid rectangle. The host application is expected to draw the pin bubble within the specified rectangle.

typedef boolean (CALLBACK* NBI_MapPinBubbleDrawCallback) (
  void* appData , 
  NBI_Map* map , 
  Canvas* canvas , 
  int PinID , 
  int x , 
  int y );

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Canvas*

canvas

Platform-specific object containing the object required to drawn on the screen.

int

PinID

ID of the pin that needs to be drawn.

int

x, y

Coordinates of the pin in the screen's coordinate system.

NBI_Error NBI_Error NBI_MapSetPinBubbleDrawCallback (
  NBI_Map* map , 
  NBI_MapPinBubbleDrawCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinBubbleDrawCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinDragEndCallback

The NBI_MapSetPinDragEndCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the user finishes dragging a pin. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapPinDragEndCallback) (
  void* appData , 
  NBI_Map* map , 
  int PinID, 
  NBI_Coordinates* moveTo , 
  int* okToMove );

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

PinID

ID of the pin being moved.

NBI_Coordinates*

moveTo

Coordinates of the end point after dragging the pin.

int*

okToMove

The application should set this to non-zero to enable the pin to be dragged to the new location. Setting it to zero cancels pin dragging and the pin reverts to the start position.

NBI_Error NBI_MapSetPinDragEndCallback (
  NBI_Map* map , 
  NBI_MapPinDragEndCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinDragEndCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinDragRequestCallback

The NBI_MapSetPinDragRequestCallback function takes as input a function pointer and a pointer to app-provided data and calls the function whenever the user attempts to drag a pin. To disable the callback, call the function with a NULL pointer.

Note: the trigger for this callback varies depending on the platform and whether or not touch is supported. On touch capable platforms, the function is called if the user touches a pin for over a second.

typedef void (CALLBACK* NBI_MapPinDragRequestCallback) (
  void* appData , 
  NBI_Map* map , 
  int PinID , 
  NBI_Pin* pinDuringDrag , 
  int* okToDrag );

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

PinID

ID of the pin being moved.

NBI_Pin*

pinDuringDrag

Points to a pin structure in the MapKit, which defaults to no change. The application can modify the pin image to change its appearance during the drag action.

int*

okToDrag

The application should set this to non-zero to enable the pin to be dragged. Setting the pin to zero prevents pin dragging; the map isdragged instead.

NBI_Error NBI_MapSetPinDragRequestCallback (
  NBI_Map* map , 
  NBI_MapPinDragRequestCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinDragRequestCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinSelectedCallback

The NBI_MapSetPinSelectedCallback function takes as input a function pointer and a pointer to app-provided data and calls the function whenever a pin is selected.

To disable the callback, call the function with a NULL pointer.

Note: the trigger for this callback varies by platform and whether or not touch is supported. On touch capable platforms, the function is called if the user touches a pin.

typedef void (CALLBACK* NBI_MapPinSelectedCallback)(
  void* appData,
  NBI_Map* map,
  int PinID );

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

PinID

ID of the selected pin.

NBI_Error NBI_MapSetPinSelectedCallback(
  NBI_Map * map,
  NBI_MapPinSelectedCallback callback,
  void *appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinSelectedCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinTouchedCallback

The NBI_MapSetPinTouchedCallback function takes as input a function pointer and a pointer to app-provided data and calls the function whenever the user touches a pin. If the pin is selected, the function passes a flag to determine if the pin or the bubble was touched.

To disable the callback, call the function with a NULL pointer.

Note: the trigger for this callback varies by platform and whether or not touch is supported. On touch capable platforms, the function is called if the user touches a pin.

typedef void (CALLBACK* NBI_MapPinTouchedCallback) (
  void* appData , 
  NBI_Map* map , 
  int PinID , 
  int inBubble );

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

PinID

ID of the touched pin.

int

inBubble

If the pin is touched  within the boundaries of the bubble, then this parameter is a non-zero value.

NBI_Error NBI_MapSetPinTouchedCallback (
  NBI_Map* map , 
  NBI_MapSetPinTouchedCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapSetPinTouchedCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetPinTrafficBubbleTouchedCallback

The NBI_MapSetPinTrafficBubbleTouchedCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the user touches the bubble of a traffic incident pin so the host application can display the details of a traffic incident.

To disable the callback, call the function with a NULL pointer.

Note: the trigger for this callback varies by platform and whether or not touch is supported. On touch capable platforms, the function is called if the user touches a pin.

typedef void (CALLBACK* NBI_MapPinTrafficBubbleTouchedCallback)(
  void* appData,
  NBI_Map* map,
  NBI_TrafficIncident* incident);

Type

Name

Description

void*

appData

Context passed to the callback by the application.

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_TrafficIncident*

incident

Structure containing traffic incident information to be displayed by the host application.

NBI_Error NBI_MapSetPinTrafficBubbleTouchedCallback(
  NBI_Map * map ,
  NBI_MapPinTrafficBubbleTouchedCallback callback ,
  void *appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapPinTrafficBubbleTouchedCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetResizeCallback

The NBI_MapSetResizeCallback function takes as input a function pointer and a pointer to application-provided data and calls the function whenever the size of the map changes. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapResizeCallback) (
  void* appData , 
  NBI_Map* map , 
  int width , 
  int height );

NBI_Error NBI_MapSetResizeCallback (
  NBI_Map* map , 
  NBI_MapResizeCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapResizeCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.
NBI_MapSetTrafficVisibleChangeCallback

The NBI_MapSetTrafficVisibleChangeCallback function takes as input a function pointer and a pointer to the application-provided data and calls the function whenever the state of the traffic layer changes. To disable the callback, call the function with a NULL pointer.

typedef void (CALLBACK* NBI_MapTrafficVisibleChangeCallback) (
  void* appData , 
  NBI_Map* map , 
  int showTraffic , 
  int byUserAction );

NBI_Error NBI_MapSetTrafficVisibleChangeCallback (
  NBI_Map* map , 
  NBI_MapTrafficChangeCallback callback , 
  void* appData )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapTrafficChangeCallback

callback

Callback function pointer, see above for description.

void*

appData

Context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: the callback has been set/cleared.

PIN MANAGER

The Pin Manager provides an API to add and edit pins on the map. Each pin is added with an associated type. Based on the pin image and whether it can be selected or not, a pin can also display a bubble containing location information. Only one pin can be selected at a time. These functions operate on the default POI Layer.

NBI_MapAddPin
NBI_MapDeselectAllPins
NBI_MapDropPin
NBI_MapGetPin
NBI_MapGetNextPin
NBI_MapGetPreviousPin

NBI_MapGetSelectedPinID
NBI_MapRemovePin
NBI_MapRemoveAllPins
NBI_MapSelectPin
NBI_MapGetPinCount
NBI_MapSetPin

NBI_MapSetPinImage
NBI_MapSetStandardPinImage
NBI_MapZoomToAllPins
NBI_MapZoomToAllPinsIntoRect
NBI_MapZoomToPin

NBI_MapAddPin

The NBI_MapAddPin function takes as input a coordinate point for the pin location, an NBI_Pin, a Boolean specifying if the pin should be added in the selected state, and a Boolean specifying if the pin should be zoomed to.

NBI_Error NBI_MapAddPin (
  NBI_Map* map ,
  NBI_Pin* pin ,
  boolean selected , 
  boolean zoom , 
  int* pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Pin*

pin

Pin data structure added to the list of active pins. 
Note: The host application is responsible for managing this structure, NBI will just make a copy of it.

boolean

selected

If TRUE, the pin is selected and a bubble is shown.

boolean

zoom

If TRUE, the map is automatically zoomed to this pin.

int*

pinID

Output parameter containing the ID of a pin on the active list.

Possible return values:
  • NBI_SUCCESS: successful call, the pin is added as requested and its ID is returned in the pinID parameter.
  • NBI_ERROR_INVALID_PIN_TYPE: unknown pin type.
  • NBI_ERROR_NO_IMAGE_ALLOWED: trying to add an image to a pin type that does not support it.
  • NBI_ERROR_INVALID_LOC: the requested position is not a valid coordinate pair.
  • NBI_ERROR_BAD_PLACE: the place structure contains errors.
NBI_MapDeselectAllPins

The NBI_MapDeselectAllPins function sets the state of all pins on the map to deselected and redraws the map as needed. The function takes no arguments and returns no values.

NBI_Error NBI_MapDeselectAllPins ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, the pin is added as requested and its ID is returned in the pinID parameter.
  • NBI_ERROR_INVALID_MAP: the map parameter is NULL.
NBI_MapDropPin

The NBI_MapDropPin function takes as input a coordinate point in the view's coordinate system. The function does the following automatically:

  • Adds a new user pin at the requested position and returns the ID in the pinID parameter.
  • If the device has a touch screen, the function inserts the first line of the bubble text to "Drag to move pin".
  • Submits a reverse geocode request with the pin's location.
  • When the reverse geocode result is received, the function sets the pin location data to the received data and the second line of the bubble to the formatted address.
  • If the pin bubble is being shown when the reverse geocode result arrives, the pin bubble is automatically redrawn to show the updated data.
  • Handles dragging of the pin automatically, reissuing the reverse geocode each time the pin is moved to a new position.

NBI_Error NBI_MapDropPin (
  NBI_Map* map ,
  int x , 
  int y , 
  int* pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x

Initial x location of the pin in the view's coordinate system.

int

y

Initial y location of the pin in the view's coordinate system.

int*

pinID

ID of the new pin.

Possible return values:
  • NBI_SUCCESS: successful call, the pin is added as requested and its ID is returned in the pinID parameter.
  • NBI_ERROR_INVALID_LOC: the requested position is outside the map boundary.
NBI_MapGetPin

The NBI_MapGetPin function obtains a local copy of the pin structure with the requested pinID.

Note: if the developer uses NBI_PINTYPE_CUSTOM_IMAGE to associate an image with the pin, then the caller MUST release the returned image data (pin.imageData) when done to  prevent memory leaks.

NBI_Error NBI_MapGetPin ( NBI_Map* map, int pinID, NBI_Pin* pin )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin in the active list.

NBI_Pin*

pin

Pointer to an NBI_Pin structure that receives a copy of the pin information.

Possible return values:
  • NBI_SUCCESS: a copy of the pin is placed in the structure pointed to by the pin parameter.
  • NBI_ERROR_INVALID_PINID: if the ID does not exist.
NBI_MapGetNextPin

The NBI_MapGetNextPin function obtains the ID of the next pin from the list. If pinID is the last pin of the list, then -1 is returned. If pinID is -1, then the first pin of the list is returned.

int NBI_MapGetNextPin ( NBI_Map* map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the current pin from the active list.

Possible return values:
  • The ID of the next pin from the list.
  • -1: if pinID is the last pin of the list.
NBI_MapGetPreviousPin

The NBI_MapGetPreviousPin function obtains the ID of the previous pin from the list. If pinID is the first pin of the list, then -1 is returned.  If pinID is -1, then the last pin of the list is returned.

int NBI_MapGetPreviousPin ( NBI_Map* map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the current pin from the active list.

Possible return values:
  • The ID of the previous pin of the list.
  • -1: if pinID is the first pin of the list.
NBI_MapGetSelectedPinID

The NBI_MapGetSelectedPinID function returns the ID of the currently selected pin or NBI_ERROR_NO_PIN_SELECTED if no pins are selected.

int NBI_MapGetSelectedPinID ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • The ID of the selected pin.
  • NBI_ERROR_NO_PIN_SELECTED if no pins are selected.
NBI_MapRemovePin

The NBI_MapRemovePin function removes an existing pins from the current list and redraws the map as needed.

NBI_Error NBI_MapRemovePin ( NBI_Map * map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin to removed. If the pin is not found, the function returns an error and does nothing.

Possible return values:
  • NBI_SUCCESS: successful call, the pin is removed.
  • NBI_ERROR_INVALID_PIN_ID: the requested pinID does not exist.
NBI_MapRemoveAllPins

The NBI_MapRemoveAllPins function removes all existing pins from the current list and redraws the map as needed. The function takes no arguments and does not return a value.

NBI_Error NBI_MapRemoveAllPins ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, the pin is removed.
  • NBI_ERROR_INVALID_MAP: the map parameter is NULL.
NBI_MapSelectPin

The NBI_MapSelectPin function selects the pin at pinID and deselects all other pins. If the pin is visible on the screen, the map is panned to fully show the pin and its bubble.. If the pin is not visible, NBI_MapZoomToPin is called to show the pin centered on the map. An error is returned if the requested ID does not exist and the selected pin does not change.

NBI_Error NBI_MapSelectPin ( NBI_Map* map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin from the active list.

Possible return values:
  • NBI_SUCCESS: successful call, the pin at pinID is now selected.
  • NBI_ERROR_INVALID_PINID: the pinID does not exist. No changes are made.
NBI_MapGetPinCount

The NBI_MapGetPinCount function returns the count of pins from the list.

int NBI_MapGetPinCount( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • Number of pins from the list.
NBI_MapSetPin

The NBI_MapSetPin function updates the pin at pinID with new pin data from the parameter. If select is true, then NBI_MapSelectPin is called to select the pin after the update.

NBI_Error NBI_MapSetPin (
  NBI_Map* map ,
  int pinID ,
  NBI_Pin* pin ,
  boolean select )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin from the active list.

NBI_Pin*

pin

Pin data that replaces existing data.

Boolean

select

If TRUE, the updated pin is selected.

Possible return values:
  • NBI_SUCCESS: successful call, the pin at pinID is now updated.
  • NBI_ERROR_INVALID_PINID: the ID does not exist. No changes made to the pins.
  • NBI_ERROR_INVALID_PIN_TYPE: unknown pin type.
  • NBI_ERROR_NO_IMAGE_ALLOWED: trying to add an image to an unsupported pin type.
  • NBI_ERROR_INVALID_LOC: the requested position is not a valid coordinate pair.
  • NBI_ERROR_BAD_PLACE: the place structure contains errors.
NBI_MapSetPinImage

The NBI_MapSetPinImage function updates the pin at pinID with the new image data in the parameter.

NBI_Error NBI_MapSetPinImage ( NBI_Map* map, int pinID, NBI_PinImage* image )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin from the active list.

NBI_PinImage*

image

Structure containing the new pin image.

Possible return values:
  • NBI_SUCCESS: successful call, the pin at pinID is now updated with the new image.
  • NBI_ERROR_INVALID_PINID: the ID does not exist. No changes made to the pins.
  • NBI_ERROR_NO_IMAGE_ALLOWED: trying to add an image to an unsupported pin type.
NBI_MapSetStandardPinImage

The NBI_MapSetStandardPinImage function enables the host application to use different images for standard pin types. Changing the pin image of a standard pin type causes all pins of this type to switch to the new image.

NBI_Error NBI_MapSetStandardPinImage (
  NBI_Map* map , 
  NBI_PinType pinType , 
  NBI_PinImage* image )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_PinType

pinType

Pin type for which the standard pin image is changed.

NBI_PinImage*

image

Structure containing the new standard pin image. The default standard image for this type is no longer available.

Possible return values:
  • NBI_SUCCESS: successful call, the standard pin image is replaced with a new image.
  • NBI_ERROR_NO_IMAGE_ALLOWED: trying to add an image to a pin of type.
  • NBI_ERROR_PINTYPE_CUSTOM_IMAGE. Use SetPinImage instead, but the image applies to only one pin.
NBI_MapZoomToAllPins

The NBI_MapZoomToAllPins function calculates the bounding box for all existing pins and calls NBI_MapZoomToBoundingBox to resize the map to show all pins. Default max zoom level is set to 15 for 1 or multiple PINS.

NBI_Error NBI_MapZoomToAllPins ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, all pins are shown on the map.
  • NBI_ERROR_NO_PINS_FOUND: there are no pins in the list. No changes made to the map.
NBI_MapZoomToAllPinsIntoRect

The NBI_MapZoomToAllPinsIntoRect is the same as NBI_MapZoomToAllPins, but it allows the caller to specify a rectangle instead of using the entire map area.

NBI_Error NBI_MapZoomToAllPinsIntoRect( NBI_Map * map, NBI_Rectangle rect )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Rectangle

rect

Rectangle to use when zooming the map.

Possible return values:
  • NBI_SUCCESS: successful call, all pins are shown on the map.
  • NBI_ERROR_NO_PINS_FOUND: there are no pins in the list. No changes made to the map.
NBI_MapZoomToPin

The NBI_MapZoomToPin function specifies a map zoom level and centers the map at the coordinates of the pin at pinID. If there is no pin with the requested ID, an error is returned and nothing happens.

NBI_Error NBI_MapZoomToPin (
  NBI_Map* map ,
  int pinID , 
  int zoom=NBI_NO_ZOOM_CHANGE )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the pin from the active list.

int

zoom

Map zoom level to apply. If NBI_NO_ZOOM_CHANGE is specified, the function retains the current zoom level. To highlight a single pin, the application should use NBI_VIEW_LOCATION_ZOOM.

Possible return values:
  • NBI_SUCCESS: successful call, the pin at pinID is shown on the map at the specified zoom level.
  • NBI_ERROR_INVALID_PINID: the ID does not exist. No changes made to the map view.

LAYER CONTROL

The Layer Control component of Map Kit provides functions to configure, show, or hide additional map layers.

MapKit provides a default set of layers and APIs to add or remove additional layers.

The following standard map layers are supported:

  • Base Map: the map layer is always visible, but its type can be switched between map, satellite, and hybrid (satellite with road labels).
  • Traffic: shows traffic speeds on major roads and freeways.
  • Route: shows a route overlay that draws a route between two map locations.
  • Traffic incidents: shows a pin layer containing traffic incidents as pins on the map.
  • Location: the location layer contains a location pin to show the device position within an error radius.

In addition, MapKit enables applications to show custom map layers in a hierarchy. There are five types of map layers:

  • Opaque tile layers, which replace the Base Map layer within an area (NBI_LAYERTYPE_BASE).
  • Overlay tile layers, which appear on top of the Base Map or an opaque layer (NBI_LAYERTYPE_OVERLAY).
  • Overlay tile layers with labels, which appear on top of all map tiles to show labels (i.e. street names)
    (NBI_LAYERTYPE_OVERLAY_LABELS).
  • POI layers, which consist of pins drawn on top of the map tile layers. (NBI_LAYERTYPE_POI) POI layers can be:
    • Automatic, meaning that MapKit uses a URL to fetch data on demand as the map is moved.
    • Manual, meaning that the application fills the layer with pins using Pin Manager functions.
  • PIN layers, which consist of pins drawn on the map on top of existing POI layers, the location layer, the default pin layer, and traffic incidents layer (NBI_LAYERTYPE_PIN).
    • Automatic, meaning that MapKit uses a URL to fetch data on demand as the map is moved.
    • Manual, meaning that the application fills the layer with pins using Pin Manager functions.

NBI_MapAddPOILayer
NBI_MapAddMapLayer
NBI_MapDestroyLayer
NBI_MapGetLocation
NBI_MapGetViewType

NBI_MapIsRouteLayerVisible
NBI_MapIsTrafficIncidentsLayerVisible
NBI_MapIsTrafficLayerVisible
NBI_MapSetCursorMode
NBI_MapSetViewType
NBI_MapShowLayer
NBI_MapIsLayerVisible

NBI_MapShowLocation
NBI_MapShowRouteLayer
NBI_MapShowTrafficIncidents
NBI_MapShowTrafficLayer
NBI_MapUpdateLocation
NBI_MapUpdateLocationWithHeading

NBI_MapGetDefaultPOILayer
NBI_MapAllLayersGetNextPin
NBI_MapAllLayersGetPreviousPin
NBI_MapAllLayersGetPinCount
NBI_MapAllLayersRemoveAllPins
NBI_MapAllLayersZoomToAllPins

NBI_MapLayerGetNextPin
NBI_MapLayerGetPreviousPin
NBI_MapLayerGetPinCount
NBI_MapLayerRemoveAllPins
NBI_MapLayerZoomToAllPins
NBI_MapLayerZoomToAllPinsIntoRect

NBI_MapAddPOILayer

The NBI_MapAddPOILayer function enables the host application to add a new POI layer to the map object. There are two types of POI layers: automatic and manual. An automatic POI layer uses a developer-provided URL to fetch POIs and add them to the layer automatically as the map location moves. The manual POI layer creates a new empty pin list that can be used with Pin Manager to manually add orremove map pins.

If the user adds a $user parameter in the URL, the userParameterCallback in the NBI_MapAddPOILayer cannot be NULL. This parameter must point to a handler defined of the following type, and its return value must be a heap allocated string containing the replacement value for the parameter. MapKit replaces the value in the URL before sending it to the server and frees memory.

typedef char * (CALLBACK* NBI_MapUserParameterCallback) (
  NBI_Map* map ,
  NBI_Layer* layer ,
  const uint x ,
  const uint y ,
  const uint z ,
  const char* q ,
  const uint sz ,
  const void* appData
);

Automatic POI layers include an extraction function callback parameter that is called when MapKit receives new POI data from the server.  The application must implement this function, and decode the data in the buffer, adding the necessary pins to the POI layer.  MapKit automatically removes pins from the POI layer when the pins move offscreen.

typedef char * (CALLBACK* NBI_ POIExtractionCallback) (
  NBI_Map* map ,
  NBI_Layer* layer ,
  void* buffer
);

NBI_Error NBI_MapAddPOILayer( NBI_Map* map, int layerType, NBI_Layer** layer )

NBI_Error NBI_MapAddPOILayer(
  NBI_Map* map ,
  char* layerURL ,
  NBI_BoundingBox* layerBoundingBox ,
  uint minimumZoomAllowed ,
  uint maximumZoomAllowed ,
  NBI_LayerType layerType ,
  uint validityPeriod ,
  POIExtractionCallback extractionCallback ,
  NBI_MapUserParameterCallback userParameterCallback ,
  void* userData ,
  NBI_Layer** layer)

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

char*

layerURL

URL used by the map object to pull tiles from the server.

NBI_BoundingBox*

layerBoundingBox

Bounding box within which this layer is active.  A null value signifies no bounding box.

uint

minimumZoomAllowed

Minimum zoom level at which this layer pulls data. If the map is zoomed to a level lower than the  minimum value, the layer data is freed.  A value of  MIN_ZOOM_LEVEL signifies the minimum threshold zoom level.

uint

maximumZoomAllowed

Maximum zoom at which this layer pull data. If the map is zoomed to a level greater than the maximum value, the layer data is freed.  A value of MAX_ZOOM_LEVEL signifies the maximum threshold zoom level.

NBI_LayerType

layerType

A constant indicating the type of POI layer being created; either NBI_LAYERTYPE_POI, or NBI_LAYERTYPE_PIN.

uint

validityPeriod

Time in seconds the data retrieved by the URL lasts. Use 0 for no expiration.

NBI_POIExtractionCallback

extractionCallback

Handler function called by MapKit when new POI data is read from the server.

NBI_MapUserParameterCallback

userParameterCallback

Handler function called by MapKit before sending each URL to the server. The application can set the value with the $user parameter in the URL.

void*

appData

Optional pointer to appData sent as a parameter to the userParameterCallback.

NBI_Layer**

layer

If the call is successful, the layer object is returned here.

Possible return values:
  • NBI_SUCCESS: successful call, the layer is added.
  • NBI_ERROR_BAD_PARAMETER: error, one or more of the parameters is invalid.
NBI_MapAddMapLayer

The NBI_MapAddMapLayer function enables the host application to add a new tile layer to the map object. The developer can add a handler to set the $user parameter in the layerURL before sending the URL to the server.

If the user adds a $user parameter in the URL, the userParameterCallback parameter in the NBI_MapAddMapLayer cannot be NULL. This parameter must point to a handler defined of the following type, and its return value must be a heap allocated string containing the replacement value for the parameter. MapKit replaces the value in the URL before sending it to the server and frees memory.

typedef char * (CALLBACK* NBI_MapUserParameterCallback) (
  NBI_Map* map ,
  NBI_Layer* layer ,
  const uint x ,
  const uint y ,
  const uint z ,
  const char* q ,
  const uint sz ,
  const void* appData );

NBI_Error NBI_MapAddMapLayer(
  NBI_Map* map ,
  char* layerURL ,
  NBI_BoundingBox* layerBoundingBox ,
  uint minimumZoomAllowed ,
  uint maximumZoomAllowed ,
  NBI_LayerType layerType ,
  uint validityPeriod ,
  NBI_MapUserParameterCallback userParameterCallback ,
  void* appData ,
  NBI_Layer** layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

char*

layerURL

URL used by the map object to pull tiles from the server.

NBI_BoundingBox*

layerBoundingBox

Bounding box within which this layer is active. A null value signifies no bounding box.

uint

minimumZoomAllowed

Minimum zoom level at which this layer pulls data. If the map is zoomed to a level lower than the  minimum value, the layer data is freed.  A value of  MIN_ZOOM_LEVEL signifies the minimum threshold zoom level.

uint

maximumZoomAllowed

Maximum zoom at which this layer pull data. If the map is zoomed to a level greater than the maximum value, the layer data is freed.  A value of MAX_ZOOM_LEVEL signifies the maximum threshold zoom level.

NBI_LayerType

layerType

A constant indicating the type of POI layer being created, either NBI_LAYERTYPE_BASE, NBI_LAYERTYPE_OVERLAY, or NBI_LAYERTYPE_OVERLAY_ WITH_LABELS.

uint

validityPeriod

Time in seconds the data retrieved by the URL lasts. Use 0 for no expiration.

NBI_MapUserParameterCallback

userParameterCallback

Handler function called by MapKit before sending each URL to the server, so the application can set the value of the $user parameter in the URL.

void*

appData

Optional pointer to appData, sent as a parameter to the userParameterCallback.

NBI_Layer**

layer

If the call is successful, the layer object is returned here.

Possible return values:
  • NBI_SUCCESS: successful call, the layer is added.
  • NBI_ERROR_MISSING_TILE_SIZE_PARAMETER: the URL provided does not have a $sz parameter in it, and the forceTileSize256 field in the map configuration is false.
  • NBI_ERROR_BAD_PARAMETER: error, one or more parameters is invalid.
NBI_MapDestroyLayer

The NBI_MapDestroyLayer function enables the host application to remove a map layer and release the storage associated with it, including pins (if a POI layer) and tiles (if a tile layer).

boolean NBI_MapDestroyLayer( NBI_Map* map, NBI_Layer* layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

Layer object previously created using NBI_MapAddTileLayer() or NBI_MapAddPOILayer().

Possible return values:
  • TRUE: successful call, the layer is removed from the layer collection.
  • FALSE: error, the layer does not exist in the layer collection.
NBI_MapGetLocation

The NBI_MapGetLocation function enables the host application to get the current position of the Location pin, which is used to show the device's location on the map within an error radius.

NBI_Coordinates NBI_MapGetLocation ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • The location pin coordinates.
  • (999,999) if the pin has not been previously set with NBI_MapUpdateLocation.
NBI_MapGetViewType

The NBI_MapGetViewType function returns the current view type.

NBI_MapView NBI_MapGetViewType ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, the map size is returned in the parameters.
  • NBI_ERROR_BAD_PARAMETER: error, one or more of the parameters is NULL.
NBI_MapIsRouteLayerVisible

The NBI_MapIsRouteLayerVisible function enables the host application to retrieve the state of the route layer and (if active) the route information associated with it.

boolean NBI_MapIsRouteLayerVisible (
  NBI_Map* map , 
  NBI_ManeuverList** route1 , 
  NBI_ManeuverList** route2 )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_ManeuverList**

route1, route2

On success these parameters point to data structures containing route overlay information. The route2 parameter is used when two routes are compared (for example for a detour).
Note: These structures are read only and owned by NBI.

Possible return values:
  • TRUE: successful call, the route layer is activated and the associated information is made accessible through the route1/2 parameters.
  • FALSE: the route layer is inactive.
NBI_MapIsTrafficIncidentsLayerVisible

The NBI_MapIsTrafficIncidentsLayerVisible function returns a Boolean that indicates if the traffic incidents layer is currently displayed.

boolean NBI_MapIsTrafficIncidentsLayerVisible ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • TRUE: the traffic incidents layer is active.
  • FALSE: the traffic incidents layer is inactive or not supported.
NBI_MapIsTrafficLayerVisible

The NBI_MapIsTrafficLayerVisible function returns a Boolean that indicates if the traffic layer is currently displayed.

boolean NBI_MapIsTrafficLayerVisible ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • TRUE: the traffic layer is active.
  • FALSE: the traffic layer is inactive or not supported.
NBI_MapSetCursorMode

The NBI_MapSetCursorMode function is used for applictions running on non-touch devices to control the visibility of the cursor at the center of the map. This function can be used by applications to hide the center when needed. For example, an application should hide the cursor while in follow-me mode.

Note: This function is ignored on touch devices.

void NBI_MapSetCursorMode( NBI_Map *map, boolean onOff )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Boolean

onOff

If true, show the cursor at the center of the map (default). Otherwise hide the map cursor.

NBI_MapSetViewType

The NBI_MapSetViewType function sets the map to the requested view type.

NBI_Error NBI_MapSetViewType ( NBI_Map* map, NBI_MapView viewType )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_MapView

viewType

View type of the map.

Possible return values:
  • NBI_SUCCESS: successful call, the map size is returned in the parameters.
  • NBI_ERROR_BAD_PARAMETER: the requested view type is not supported or the values is incorrect.
NBI_MapShowLayer

The NBI_MapShowLayer function enables the host application to show or hide a custom layer.

NBI_Error NBI_MapShowLayer( NBI_Map* map, NBI_Layer* layer, boolean onOff )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

Custom tile layer or a POI layer.

boolean

onOff

If TRUE, the map layer is shown.

Possible return values:
  • NBI_SUCCESS: successful call, the map layer is shown or hidden successfully.
  • NBI_ERROR_BAD_PARAMETER: the layer object is invalid.
NBI_MapIsLayerVisible

The NBI_MapIsLayerVisible function enables the host application to validate if a custom map layer is currently visible.

NBI_Error NBI_MapIsLayerVisible( NBI_Map* map, NBI_Layer* layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

Custom tile layer or a POI layer.

Possible return values:
  • TRUE: the custom map layer is visible.
  • FALSE: the custom map layer is not visible.
NBI_MapShowLocation

The NBI_MapShowLocation function enables the host application to show or hide the location pin, which shows the device's location on the map within an error radius.

NBI_Error NBI_MapShowLocation ( NBI_Map* map, boolean onOff )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

boolean

onOff

If TRUE, the location pin is shown.

Possible return values:
  • NBI_SUCCESS: successful call, the location pin is made visible.
  • NBI_ERROR_NO_LOCATION: NBI_MapUpdateLocation must be called at least once to initialize the location pin before showing it.
NBI_MapShowRouteLayer

The NBI_MapShowRouteLayer function enables the host application to show or hide the directions layer and to adjust the map size and position to show the route. The function enables the application to pass one or two maneuver lists, which can be obtained when the user requests a route.. The second route can be used to show alternative routes to a destination. The function also enables the application to specify a color for each route, and to automatically adjust the map view to fit the route within the visible portion of the map.

NBI_Error NBI_MapShowRouteLayer (
  NBI_Map* map ,
  NBI_ManeuverList* route1 , 
  NBI_ManeuverList* route2 ,
  boolean onOff , 
  boolean adjust )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_ManeuverList*

route1, route2

Data structures containing

char*

routeColor1, routeColor2

Colors of the route overlay. If NULL is passed, default colors are used.

boolean

onOff

If TRUE, the route layer is shown.

boolean

adjust

If TRUE, the map view is resized to show the entire route(s).

Possible return values:
  • NBI_SUCCESS: successful call, the directions layer is activated and if the adjust parameter is true, the map is resized to show the entire route.
  • NBI_ERROR_INVALID_DIRECTIONS: the directions object contains invalid information.
NBI_MapShowTrafficIncidents

The NBI_MapShowTrafficIncidents function enables the host application to show or hide the traffic incidents layer (if available). If the MapKit version does not support a traffic incidents layer, this function returns an NBI_TRAFFIC_INCIDENTS_UNAVAILABLE error. The application can query MapKit to see if traffic incidents are supported by calling this function with a false parameter..

NBI_Error NBI_MapShowTrafficIncidents ( NBI_Map* map, boolean onOff )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

boolean

onOff

If TRUE, the traffic incidents layer is shown.

Possible return values:
  • NBI_SUCCESS: successful call, the traffic layer is activated.
  • NBI_ERROR_TRAFFIC_INCIDENTS_UNAVAILABLE: the traffic incidents layer is not supported.
NBI_MapShowTrafficLayer

The NBI_MapShowTrafficLayer function enables the host application to show or hide the traffic layer (if available). If the MapKit version does not support a traffic layer, this function returns an NBI_TRAFFIC_UNAVAILABLE error. The application can query MapKit to see if traffic is supported by calling this function with a false parameter.

NBI_Error NBI_MapShowTrafficLayer ( NBI_Map* map, boolean onOff )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

boolean

onOff

If TRUE, the traffic layer is shown.

Possible return values:
  • NBI_SUCCESS: successful call, the traffic layer is activated.
  • NBI_ERROR_TRAFFIC_UNAVAILABLE: the traffic layer is not supported.
NBI_MapUpdateLocation

The NBI_MapUpdateLocation function is used to initialize and update the location layer pin with location data obtained by a positional fix. The function includes several parameters to control how the map responds to the location update.

NBI_Error NBI_MapUpdateLocation (
  NBI_Map* map , 
  NBI_Coordinates coordinates , 
  int errorRadius , 
  boolean moveMap , 
  boolean zoomMap , 
  boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates

coordinates

The lat/lon coordinates of the updated position.

int

errorRadius

The error radius of this position.

boolean

moveMap

If TRUE, the function calls NBI_MapSetCenter to center the map at the new position.

boolean

zoomMap

If TRUE, the function calls NBI_MapSetZoomLevel to to set the map zoom level to show the entire location error radius as large as possible.

boolean

animate

If TRUE, the function animates the map movement to the new position and/or zoom level.

Possible return values:
  • NBI_SUCCESS: successful call, the location is updated.
  • NBI_ERROR_INVALID_COORDINATE: invalid coordinates passed.
  • NBI_ERROR_INVALID_ERROR_RADIUS: the provided error radius is not within a valid range.
NBI_MapUpdateLocationWithHeading

The NBI_MapUpdateLocationWithHeading function initializes and updates the location layer pin with fix data that includes a directional heading. The function includes several parameters to control how the map responds to the location update.

NBI_Error NBI_MapUpdateLocation (
  NBI_Map* map ,
  NBI_Location location ,
  int errorRadius ,
  boolean moveMap ,
  boolean zoomMap ,
  boolean animate )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Location

Location

A position that includes heading used to draw the position icon oriented to the directional heading.

int

errorRadius

Error radius of this position.

boolean

moveMap

If TRUE, the function calls NBI_MapSetCenter to center the map at the new position.

boolean

zoomMap

If TRUE, the function calls NBI_MapSetZoomLevel to to set the map zoom level to show the entire location error radius as large as possible.

boolean

animate

If TRUE, the function animates the map movement to the new position and/or zoom level.

Possible return values:
  • NBI_SUCCESS: successful call, the location is updated.
  • NBI_ERROR_INVALID_COORDINATE: invalid coordinates passed.
  • NBI_ERROR_INVALID_ERROR_RADIUS: the error radius provided is not within a valid range.
NBI_MapGetDefaultPOILayer

The NBI_MapGetDefaultPOILayer function enables the host application to return the default POI layer, so POILayer specific functions can be used on the default layer.

NBI_Layer * NBI_MapGetDefaultPOILayer ( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • Default POI layer object: successful call, the default POI layer is returned.
NBI_MapAllLayersGetNextPin

The NBI_MapAllLayersGetNextPin function returns the ID of the next pin from the list. If pinID is the last pin on the list, the first pin of the next POI layer is returned.  If pinID is the last pin on the last POI layer, -1 is returned.

int NBI_MapAllLayersGetNextPin( NBI_Map* map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the current pin of the active list.

Possible return values:
  • The ID of the next pin of the list.
  • -1: if pinID is the last pin of the list from the last POI layer.
NBI_MapAllLayersGetPreviousPin

The NBI_MapAllLayersGetPreviousPin function returns the ID of the previous pin from the list. If pinID is the first pin on the list, the last pin of the previous POI layer is returned. If pinID is the first pin of the first POI layer, then -1 is returned.

int NBI_MapAllLayersGetPreviousPin( NBI_Map* map, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

pinID

ID of the current pin of the active list.

Possible return values:
  • The ID of the previous pin of the list.
  • -1: if pinID is the first pin of the list from the first POI layer.
NBI_MapAllLayersGetPinCount

The NBI_MapAllLayersGetPinCount function returns the count of pins in the list.

int NBI_MapAllLayersGetPinCount( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • The number of pins from all POI map layers.
NBI_MapAllLayersRemoveAllPins

The NBI_MapAllLayersRemoveAllPins function removes all existing pins from all POI layers and redraws the map as needed. The function takes no arguments and does not return any value.

NBI_Error NBI_MapAllLayersRemoveAllPins( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, all pins are removed from the map.
  • NBI_ERROR_INVALID_MAP: the map parameter is NULL.
NBI_MapAllLayersZoomToAllPins

The NBI_MapAllLayersZoomToAllPins function calculates the bounding box for all existing pins from all POI layers and calls NBI_MapZoomToBoundingBox to resize the map and display all the pins.

NBI_Error MapAllLayersZoomToAllPins( NBI_Map* map )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

Possible return values:
  • NBI_SUCCESS: successful call, all pins are shown on the map.
  • NBI_ERROR_NO_PINS_FOUND: there are no pins in the list. No changes made to the map.
NBI_MapLayerGetNextPin

The NBI_MapLayerGetNextPin function returns the ID of the next pin of the custom POI layer.  If pinID is the last pin of the POI layer, -1 is returned.

NBI_Error NBI_MapLayerGetNextPin( NBI_Map* map, NBI_Layer* layer, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

Custom POI layer.

int

pinID

ID of the current pin of the POI layer.

Possible return values:
  • The ID of the next pin on the list.
  • -1: if pinID is the last pin of the POI layer.
NBI_MapLayerGetPreviousPin

The NBI_MapLayerGetPreviousPin function returns the ID of the previous pin of the custom POI layer. If pinID is the first pin in the POI layer, then -1 is returned.

NBI_Error NBI_MapLayerGetPreviousPin( NBI_Map* map, NBI_Layer* layer, int pinID )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

Custom POI layer.

int

pinID

ID of the current pin of the POI layer.

Possible return values:
  • The ID of the previous pin of the list.
  • -1: if pinID is the first pin in the POI layer.
NBI_MapLayerGetPinCount

The NBI_MapLayerGetPinCount function returns the count of pins in the POI layer.

NBI_Error NBI_MapLayerGetPinCount( NBI_Map* map, NBI_Layer* layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

A custom POI layer.

Possible return values:
  • The number of pins in the POI layer.
NBI_MapLayerRemoveAllPins

The NBI_MapLayerRemoveAllPins function removes all pins from the POI layer and redraws the map as needed. The function takes no arguments and does not return any value.

NBI_Error NBI_MapLayerRemoveAllPins( NBI_Map* map, NBI_Layer* layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

A custom POI layer.

Possible return values:
  • NBI_SUCCESS: successful call, all pins are removed from the map.
  • NBI_ERROR_INVALID_MAP: the layer parameter is NULL.
NBI_MapLayerZoomToAllPins

The NBI_MapLayerZoomToAllPins function calculates the bounding box for all pins in the POI layer and calls NBI_MapZoomToBoundingBox to resize the map and display all pins.

NBI_Error NBI_MapLayerZoomToAllPins( NBI_Map* map, NBI_Layer* layer )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

A custom POI layer.

Possible return values:
  • NBI_SUCCESS: successful call, all pins appear on the map.
  • NBI_ERROR_NO_PINS_FOUND: there are no pins in the list. No changes made to the map.
NBI_MapLayerZoomToAllPinsIntoRect

The NBI_MapLayerZoomToAllPinsIntoRect is the same as NBI_MapLayerZoomToAllPins, but it enables the caller to specify a rectangle instead of the entire map area.

NBI_Error NBI_MapLayerZoomToAllPinsIntoRect( NBI_Map* map, NBI_Rectangle rect )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Layer*

layer

A custom POI layer.

NBI_Rectangle

rect

Rectangle to use when zooming

Possible return values:
  • NBI_SUCCESS: successful call, all pins appear on the map.
  • NBI_ERROR_NO_PINS_FOUND: there are no pins in the list. No changes made to the map.

UTILITIES

NBI_LaunchDealURL

The NBI_LaunchDealURL function takes an NBI_Information object that was received from a coupon search containing deals, an index into the deal coupon selected and a Boolean specifying whether to launch the deal in an in-application browser or in a standalone browser.

The function verifies that a deal URL is available for this index, and if so, it registerse the event in the coupon analytics and launches the URL as specified.

NBI_Error NBI_LaunchDealURL (
  NBI_Information* information ,
  int index ,
  boolean useInAppBrowser )

Type

Name

Description

NBI_Information*

information

The NBI_Information object returned as a result of the coupon search.

int

index

The index to the desired coupon.

boolean

useInAppBrowser

If true, attempt to launch the URL in an application-provided web view. If no view is found, use the browser.

Possible return values:
  • NBI_SUCCESS: successful call, the analytics are submitted and the deal URL is launched.
  • NBI_ERROR_BAD_INFORMATION: the provided NBI_Information does not contain mobile coupons.
  • NBI_ERROR_BAD_INDEX: the provided NBI_Information does not contain a deal URL at the requested index.
  • NBI_ERROR_NO_BROWSER_VIEW: useInAppBrowser is true but the application does not provide a browser view. The analytics are still submitted and the deal URL is shown using the platform's browser instead.
NBI_RecordCouponAnalyticsEvent

The NBI_ RecordCouponAnalyticsEvent function records coupon analytics events at the NBI Server. These events are used for statistics related to coupon usage.

The following events should be recorded by an application using the coupons API:

  • NBI_CouponAnalyticsEvent_Display should be submitted when the coupon is displayed from a list.
  • NBI_CouponAnalyticsEvent_ViewDetails should be submitted when the coupon details are shown on the screen.
  • NBI_CouponAnalyticsEvent_Call should be submitted when the user clicks on a coupon's phone number to call the retailer (if supported by the application).
  • NBI_CouponAnalyticsEvent_Navigate should be submitted when the user requests a navigation session to a retailer (if supported by the application).

NBI_Error NBI_RecordCouponAnalyticsEvent (
  NBI_Contect* context ,
  NBI_CouponAnalyticsEvent event ,
  NBI_MobileCoupon* coupon ,
  NBI_Store* store )

Type

Name

Description

NBI_Context*

context

The context is an opaque structure used by NBI to maintain all state variables.

NBI_CouponAnalyticsEvent

event

Type of recorded event.

NBI_MobileCoupon*

coupon

Coupon data of this event.

NBI_Store*

store

Store data corresponding to the coupon for this event.

Possible return values:
  • SUCCESS: The coupon event was recorded.
  • NBI_Error_InvalidEventType: The requested event type is not supported.
NBI_ByteArrayToMobileCoupon

The NBI_ByteArrayToMobileCoupon function takes an array of bytes and its length that were previously created using NBI_MobileCouponToByteArray and recreates the original NBI_MobileCoupon structure from it.

NBI_Error NBI_ByteArrayToMobileCoupon (
  byte* array ,
  int length ,
  NBI_MobileCoupon* coupon )

Name

Type

Description

byte*

array

Data returned from a previous call to NBI_MobileCouponToByteArray.

int

length

Length of the array in bytes.

NBI_MobileCoupon*

coupon

Reconstructed NBI_MobileCoupon. It is the responsibility of the caller to allocate and release this data structure.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_MobileCoupon is returned in the coupon parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided array is NULL or there are errors decoding the array.
NBI_MapByteArrayToPlace

The NBI_MapByteArrayToPlace function takes an array of bytes and its length that were previously created using NBI_MapPlaceToByteArray and recreates the original NBI_Place structure from it.

NBI_Error NBI_MapByteArrayToPlace (
  NBI_Map* map ,
  byte* placeAsArray , 
  int length , 
  NBI_Place* place )

Type

Name

Description

NBI_Map*

map

NBI map created with NBI_MapCreate().

byte*

placeAsArray

Data returned from a previous call to NBI_MapPlaceToByteArray.

int

length

Length of the array in bytes.

NBI_Place*

place

Reconstructed NBI_Place. It is the responsibility of the caller to allocate and release this data structure.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_Place is returned in the place parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided placeAsArray is NULL or there are errors decoding the array.
NBI_MapConvertCoordinatesToMapXY

The NBI_MapConvertCoordinatesToMapXY function converts a (lat,lon) coordinate pair to (x,y) coordinates on the map at the current zoom level.

NBI_Error NBI_MapConvertCoordinatesToMapXY (
  NBI_Map* map , 
  NBI_Coordinates coordinates ,
  int* x ,
  int* y )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates

coordinates

Lat/long coordinate pair to convert to coordinates on a map.

int*

x, y

Output parameters that contain the corresponding x,y coordinates at the map's current zoom level.

Possible return values:
  • NBI_SUCCESS: successful call, the x and y contain the converted values.
  • NBI_ERROR_INVALID_LOC: the requested position is not a valid coordinate pair.
NBI_MapConvertMapXYToCoordinates

The NBI_MapConvertMapXYToCoordinates function converts an (x,y) coordinate pair at the map's current zoom level to a (lat,lon) pair.

NBI_Error NBI_MapConvertMapXYToCoordinates (
  NBI_Map* map ,
  int x , 
  int y , 
  NBI_Coordinates *coordinates )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x, y

x,y coordinates at the map's current zoom level to convert

NBI_Coordinates

coordinates

Output parameters containing the corresponding lat/lon coordinates.

Possible return values:
  • NBI_SUCCESS: successful call, the lat and lon contain the converted values.
  • NBI_ERROR_INVALID_POSITION: the requested position is not within the map bounding box at the current zoom level.
NBI_MapCreateImage

The NBI_MapCreateImage function takes a snapshot of a rectangle enclosing a visible part of the map starting at (x,y) with a specified width and height. The destination bitmap can be provided by the caller, or it can be automatically created by the function.

Note: on Java platforms, due to language differences, two different functions are provided: createImage and getImage. createImage automatically allocates the image buffer and getImage takes it as a parameter.

NBI_Error NBI_MapCreateImage (
  NBI_Map* map ,
  int x , 
  int y , 
  int width , 
  int height ,
  NBI_Image** image )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x

Left coordinate of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

y

Top coordinate of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

width

Width of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

height

Height of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

NBI_Image**

image

Image object in the platform’s native format. If *image is non-null, it is assumed to be a pointer to an image buffer of the appropriate size (the bitmap size is width*height*bitmapdepth/8). This enables the host application to recycle the same bitmap buffer.
If *image is null, the function automatically allocates the bitmap.

Possible return values:
  • NBI_SUCCESS: successful call, the image is returned in the image parameter.
  • NBI_ERROR_MISSING_TILES: the requested rectangle overlaps at least one missing tile.
  • NBI_ERROR_BAD_IMAGE_SIZE: the buffer that was provided is the wrong size for the requested image.
NBI_MapDestroyImage

The NBI_MapDestroyImage function takes an NBI_Image that was previously created using NBI_MapCreateImage and releases the associated memory.

NBI_Error NBI_MapDestroyImage (
  NBI_Map* map , 
  NBI_Image** image )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Image**

image

Image object in the platform's native format.

Possible return values:
  • NBI_SUCCESS: successful call, the image is returned in the image parameter.
NBI_MapDestroyByteArray

The NBI_MapDestroyByteArray function takes a byte array that was previously created using NBI_MapPlaceToByteArray and releases the associated memory.

NBI_Error NBI_MapDestroyByteArray (
NBI_Map* map ,
byte* placeAsArray )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

byte*

placeAsArray

Data returned from a previous call to NBI_MapPlaceToByteArray.

Possible return values:
  • NBI_SUCCESS: successful call, the image is returned in the image parameter.
NBI_MapDistance

The NBI_MapDistance function calculates the distance and bearing between two points on the map. The points are passed as (lat,lon) pairs and the distance is returned in meters.

NBI_Error NBI_MapDistance (
  NBI_Map* map ,
  NBI_Coordinates* point1 , 
  NBI_Coordinates* point2 ,
  double* distance , 
  double* bearing )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

NBI_Coordinates*

point1, point2

Points on a map that will be used to calculate distance and bearing.

double*

distance

Calculated distance between the two points in meters.

double*

bearing

Bearing in degrees from the first to second map point, going from 0-degrees to the second point in a clockwise direction.

Possible return values:
  • NBI_SUCCESS: successful call, the lat and lon contain the converted values.
  • NBI_ERROR_INVALID_POSITION: one or more of the requested points have bad values.
NBI_MapFromURL

The NBI_MapFromURL function takes a URL as a parameter and attempts to extract information to initialize an NBI_Map object. The following settings are extracted into the specified parameters (if available).

  • Map center
  • Map zoom level
  • Current location pin (if shown)
  • Start/End pins (if shown)
  • Map view type

The function parses the URL to extract all required settings, then calls NBI_MapCreate to initialize the map, NBI_AddPin to add the pin(s), and NBI_MapSetViewType to set the view type if different from the default. On return, map can be used to query the new map for the resulting settings.

NBI_Error NBI_MapFromURL (
  NBI_Context* context ,
  char* url ,
  NBI_MapConfiguration* configuration ,
  NBI_View* parentView ,
  NBI_Map** map )

Type

Name

Description

NBI_Context*

context

The NBI context structure that was created with NBI_ContextCreate().

char*

url

A URL representing a map in one of the supported formats.

NBI_MapConfiguration*

configuration

 

NBI_View*

parentView

The view that contains this map instance. The map is sized to the entire parent window.
Note: this is a placeholder data structure that replaced by a similar platform-dependent structure.

NBI_Map**

map

map is where the newly created object is returned. This object needs to communicate with the map functions in all remaining APIs.

Possible return values:
  • NBI_SUCCESS: the pointer to the NBI_Map is initialized to the correct values.
  • NBI_ERROR_INVALID_URL: there was an error processing the URL.
NBI_MapIsImageReady

The NBI_MapIsImageReady function is used before calling NBI_MapCreateImage or NBI_MapGetImage to query the map view to see if all tiles have been successfully downloaded to cover a rectangle enclosing a visible part of the map starting at (x,y) with a specified width and height. If the function returns false, then calling the NBI_MapCreate/GetImage functions results in incomplete images.

Note: passing an area that is not fully enclosed by the visible rectangle results in false being returned. The specified rectangle should be the same size as one that will be used in the subsequent call to NBI_MapCreate/GetImage.

boolean NBI_MapIsImageReady(
  NBI_Map* map ,
  int x ,
  int y ,
  int width ,
  int height )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

int

x

Left coordinate of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

y

Top coordinate of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

width

Width of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

int

height

Height of the rectangular area from which the image snapshot will be taken (clipped to the visible area).

Possible return values:
  • true: all map tiles for the specified area of the screen have been successfully downloaded.
  • false: one or more map tiles are missing, or the image area is invalid.
NBI_MapGetAPILevel

The NBI_MapGetAPILevel function returns a number representing the supported API level for the version of MapKit. being used. Each time a NBI release adds or changes functionality, the API level increments by 1. MapKit ensures compatibility for applications written for a lower API level, but not higher.

int NBI_MapGetAPILevel ( NBI_Context* context )

Type

Name

Description

NBI_Context*

context

NBI context structure created with NBI_ContextCreate().

Possible return values:
  • <API level> an integer representing the API level of the NBI libraries being used.
NBI_MapGetRoutingIconImage

The NBI_MapGetRoutingIconImage function retrieves the image associated with a routing icon ID. MapKit supports different routing icon sizes for different use cases. This  function enables the caller to specify the desired size of the routing icon image.

NBI_Error NBI_MapGetRoutingIconImage (
  NBI_Map* map ,
  char* routingIconName ,
  NBI_Image* routingIconImage )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

char*

routingIconName

String representing the routing icon. This string is usually obtained from the NBI_Maneuver that is returned from the directions API.

NBI_Image*

routingIconImage

Pointer to structure to be filled in with image information. The image data is owned by the map object and will be available until the next NBI_MapGetRoutingIconImage call or until the map is destroyed.

Possible return values:
  • NBI_SUCCESS: successful call, the requested routing icon is returned in routingIcon.
  • NBI_ERROR_UNKNOWN_ROUTING_ICON_CODE: the code passed is not supported or is invalid.
NBI_MapIsNavigationAvailable

The NBI_MapIsNavigationAvailable function performs application discovery to determine if the host application can issue a successful navigation command. Applications should query this API before displaying UI elements that enable the user to issue a navigation command.

boolean NBI_MapIsNavigationAvailable ( void )

Possible return values:
  • TRUE: A navigation application is available to respond to the navigation command.
  • FALSE: The navigation application is not installed. Issuing the NBI_MapNavigateTo command will fail.
NBI_MapNavigateTo

The NBI_MapNavigateTo function issues a navigation command to VZ Navigator using the app2app API. The host application uses this call to avoid the complexity of constructing the URL and invoking it, which is platform-dependent.

The place structure must meet the following conditions, or the navigation request to VZ Navigator will fail:

  • It must contain a valid address because VZ Navigator geocodes the address before starting the navigation session.
  • If a coordinate pair is passed, it must be inside the US and routable. Passing a coordinate pair will cause VZ Navigator to ignore all other fields in the place structure for navigation purposes.

The function provides different behavior based on the value of the immediate flag. If TRUE, the VZ Navigator is launched and the navigation session begins immediately (provided the data in the place structure is valid). If FALSE, VZ Navigator shows the Preview/Directions view.

NBI_Error NBI_MapNavigateTo (
  char* credential ,
  NBI_Place* place ,
  NBI_RouteType routeType ,
  unsigned int routeAvoid ,
  NBI_TransportationMode mode ,
  boolean immediate )

Type

Name

Description

char *

credential

Credential for the app2app API. This field is currently ignored and added for completeness only.

NBI_Place*

place

An NBI_Place containing the destination included in the navigation command.

NBI_RouteType

routeType

Navigation route type.

unsigned int

routeAvoid

Type of roads to avoid when creating a route. This is a number formed by or'ing one or more bit constants from the NBI_RouteAvoid enumeration.

NBI_TransportationMode

mode

Vehicle type for the route.

boolean

immediate

Flag that determines if the navigation command launches an immediate navigation session or shows the Preview/Directions screen.

Possible return values:
  • NBI_SUCCESS: successful call, the command has been sent to VZ Navigator.
  • NBI_ERROR_BAD_PARAMETER: the provided place is NULL.
NBI_MapPlaceFromLocation

The NBI_MapPlaceFromLocation function takes an NBI_Location structure and creates an NBI_Place structure that can be used wherever an NBI_Place is expected.

NBI_Error NBI_MapPlaceFromLocation (
  NBI_Map* map , 
  NBI_Location* location , 
  NBI_Place* place )

Type

Name

Description

NBI_Map*

map

NBI map structure with NBI_MapCreate().

NBI_Location*

location

Location for which the user wants to create a place.

NBI_Place*

place

NBI_Place that will the location provided on return. It is the responsibility of the application to allocate and release memory for the place structure.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_Place is returned in the place parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided location is NULL.
NBI_MapPlaceToByteArray

The NBI_MapPlaceToByteArray function takes an NBI_Place structure and creates a byte array that can be stored in a file or sent as an attachment. The symmetric function NBI_MapByteArrayToPlace can be used to rebuild the place back from the byte array.

NBI_Error NBI_MapPlaceToByteArray (
  NBI_Map* map ,
  NBI_Place* place ,
  byte** placeAsArray , 
  int* length )

Type

Name

Description

NBI_Map*

map

NBI map structure created with NBI_MapCreate().

NBI_Place*

place

NBI_Place to be flattened.

byte**

placeAsArray

Data from place presented as an array of bytes that can be saved or sent.

int*

length

Length of the array.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_Place is returned in the placeAsArray parameter and its length in the length parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided place is NULL.
NBI_MapResetTileCache

The NBI_MapResetTileCache function can be used to provide the end user with the ability to erase the NBI map tile cache.

NBI_Error NBI_Error NBI_MapResetTileCache ( NBI_Map *map )

Type

Name

Description

NBI_Map*

map

NBI map created with NBI_MapCreate().

Possible return values:
  • NBI_SUCCESS: successful call, the map tile cache has been erased and a new cache started.
NBI_MapToURL

The NBI_MapToURL function creates a URL string containing information that enables a remote instance of MapKit to reproduce the map's current view. The URL points to a web site that can correctly reproduce the map on a capable browser (the browser must support JavaScript). This enables the map URL to be viewable on systems without NBI support.

The URL captures the following information about the map's current state:

  • Map position
    • The current center of the map is saved as a coordinate pair.
  • Zoom level
    • The current zoom level is saved as a number where 0 is the map zoomed out to the maximum and NBI_MAX_ZOOM_LEVEL is the maximum supported zoom level.
  • POI location
    • The URL will allow a single location (to be used for place sharing) or a start/end pair of locations (to be used for routes or to show origin/destination).
  • Pin1 Type
    • Optional parameter that defines the type of POI for the first location.
  • Pin2 Type
    • Optional parameter that defines the type of POI for the second location.
  • Map Type
    • The map type. Currently only road and satellite map types are supported.

Note: When the mapToURL function is called,map pins are selected according to the following rules:

  • If a single pin is present, then it shall be preserved in the URL.
  • If only a start pin and a destination pins are present, then they shall be preserved in the URL.
  • For all other cases, if a pin is selected, then only that pin will be preserved in the URL. If there are multiple pins and no pin is selected or if there are no pins, then the URL shall not contain any pins.

NBI_Error NBI_MapToURL ( NBI_Map* map, char* url )

Type

Name

Description

NBI_Map*

map

map is an opaque structure that contains all state information needed to interact with the map control.

char*

url

Output parameter containing a URL that represents the current state of the map. This string is allocated by and owned by the NBI_Map. It is valid until either the NBI_Map is destroyed or another NBI_MapToURL call is issued.

Possible return values:
  • NBI_SUCCESS: successful call, the url parameter contains the map URL.
  • NBI_ERROR_INVALID_PARAMETER: the pointer to the NBI_Map is NULL or not valid.
NBI_MobileCouponToByteArray

The NBI_MobileCouponToByteArray function takes an NBI_MobileCoupon structure and creates a byte array that can be stored in a file or sent as an attachment. The symmetric function NBI_ByteArrayToMobileCoupon can be used to rebuild the mobile coupon from the byte array.

NBI_Error NBI_MobileCouponToByteArray(
  NBI_MobileCoupon* coupon ,
  byte** array ,
  int* length )

Type

Name

Description

NBI_MobileCoupon*

coupon

NBI_MobileCoupon to be marshalled.

byte**

array

Data from coupon presented as an array of bytes that can be saved or sent.

int*

length

Length of the mobile coupon array.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_MobileCoupon is returned in the array parameter and its length in the length parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided place is NULL.
NBI_SearchFilterCreate

The NBI_SearchFilterCreate function initializes a new NBI_SearchFilter object that can be used to pass key-value pairs for search requests.

NBI_SearchFilter NBI_SearchFilterCreate()

Possible return values:
  • NULL: call failed.
  • non NULL: success, key-value pairs can be added to the object.
NBI_SearchFilterAdd

The NBI_SearchFilterAdd function appends a key-value pair to an NBI_SearchFilter object.

The coupon API supports the following key-value pairs:

Key

Allowed values

Usage

“broad_category”

Broad category name

Multiple entries can be specified for broad-category. The server returns deals matching any of the requested broad-categories.

Note: the server ensures the contents are URL safe before passing them to the coupon provider.

“category”

Category name

Multiple entries can be specified for category. The server returns deals matching any of the requested categories.

Note: the server ensures the contents are URL safe before passing them to the coupon provider.

“coupon_availability”

“local”
“national”
“e-commerce”

Restricts the search results to the specified coupon locale.

“coupon_id”

Identifier value for a coupon as found in the NBI_MobileCoupon

This filter can be used to retrieve a specific coupon from the server.

“deal_quality”

“great”
“good”
“fair”

Restricts the search results based on deal quality. The default, if unspecified, is "good".

Note: it is not necessary to specify more than a single deal_quality, as the server returns results that are greater than or equal to the specified value. For example, requesting "good" returns "good" and "great" deals.

“keyword”

“hdtv”
“mp3 player”
“digital camera”
“Restaurants”
etc.

Used to filter the results. Spaces should be converted to %20 for web compatibility. If multiple keywords are provided, the server returns results matching ANY of the keywords. A keyword entry might contain multiple words, in this case, the server returns results matching ALL the words in the string.

Note: the server ensures the contents are URL safe before passing them to the coupon provider.

“mobile_compatibility”

“great”
“good”
“fair”
“poor”
“na”

Restricts the results to deals that match the criteria for mobile. The default if unspecified is "good".

Note: it is not necessary to specify more than a single deal_quality, as the server returns results that are greater than or equal to the specified value. For example, requesting "good" returns "good" and "great" deals.

“return”

“deals”
“stores”

Specifies how results are returned for deals. If set to "deals", then each element in the result is a deal, containing the deal data and a store name. If the deal is the only one for that store, then it also contains the store data. If set to "stores", then each element is a store. If the store contains a single deal, it is returned in the element. If it contains multiple deals, only a count of the deals is returned and the user must do a sub-search to see the individual deals.

Note: This key is only valid for coupon requests and is ignored in store requests. If unspecified, the default is "stores".

“store_name”

Name of the store

Name of the store to search for. This can be used after a store with multiple coupons is found to reissue the query with expandedreturn=on deals and get the individual coupons for that store.

Note: the server shall make sure the contents are URL safe before passing it to the coupon provider.

“sub_category”

Sub category name

Multiple entries can be specified for sub-category. The server will return deals matching any of the requested sub-categories.

Note: the server ensures the contents are URL safe before passing them to the coupon provider.

If multiple broad_category, category and sub-category entries are found, the query a Boolean 'OR' operation for categories/subcategories at the same level and 'AND' thems at different levels.

Example:
category=A
category=B
broad_category=C
sub_category=D
sub_category=E
sub_category=F

Should be treated as:
broad_category: (C) AND category: (A OR B) AND sub_category: (D OR E OR F)

NBI_Error NBI_SearchFilterAdd(
  NBI_SearchFilter* searchFilter ,
  const char* key ,
  const char* value )

Type

Name

Description

NBI_SearchFilter*

searchFilter

NBI_SearchFilter to which the key-value pair will be appended.

const char*

key

String to be used as the key.

const char*

value

Corresponding value.

Possible return values:
  • SUCCESS: key-value pair successfully added.
NBI_SearchFilterDestroy

The NBI_SearchFilterDestroy function releases storage associated with the specified NBI_SearchFilter object.

NBI_Error NBI_SearchFilterDestroy( NBI_SearchFilter* searchFilter)

Type

Name

Description

NBI_SearchFilter*

searchFilter

NBI_SearchFilter to destroy.

Possible return values:
  • SUCCESS: Object released.
NBI_IsServiceApplicationAvailable

The NBI_IsServiceApplicationAvailable function performs application discovery to see if the NBI service application is installed in the device. The service application provides sharing of data across multiple NBI applications. If the service application is not available, the NBI library reverts to using local data. Developers have the option of calling NBI_ServiceApplicationInstallLink() to get a link that the user can select to download and install the application.

Note: this function is available only on the Android platform.

boolean NBI_IsServiceApplicationAvailable( void )

Possible return values:
  • TRUE: The NBI Service application is available.
  • FALSE: The NBI Service application is not installed.
NBI_ServiceApplicationInstallLink

The NBI_ServiceApplicationInstallLink function provides a link to install the latest version of the service application for the platform.

Note: this function is available only on the Android platform.

char * NBI_ServiceApplicationInstallLink( void )

Possible return values:
  • <link>: The NBI Service application install link.
  • "":No link is available.
NBI_StoreToByteArray

The NBI_StoreToByteArray function takes an NBI_Store structure and creates a byte array that can be stored in a file or sent as an attachment. The symmetric function NBI_ByteArrayToStore can be used to rebuild the store from the byte array.

NBI_Error NBI_StoreToByteArray (
  NBI_Store* store ,
  byte** array ,
  int* length )

Type

Name

Description

NBI_Store*

store

NBI_Store to be marshalled.

byte**

array

Data from store presented as an array of bytes that can be saved or sent.

int*

length

Length of the array.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_Store is returned in the array parameter and its length in the length parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided place is NULL.

*Note: functions will encode/decode the place inside a store and there is no need for the user to apply NBI_PlaceToByteArray in addition.

NBI_ByteArrayToStore

The NBI_ByteArrayToStore function takes an array of bytes and its length that were previously created using NBI_StoreToByteArray and recreates the original NBI_Store structure from it.

NBI_Error NBI_ByteArrayToStore (
  byte* array ,
  int length ,
  NBI_Store* store )

Type

Name

Description

byte*

array

Data returned from a previous call to NBI_MobileCouponToByteArray.

int

length

Length of the array.

NBI_Store*

store

The reconstructed NBI_Store. It is the responsibility of the caller to allocate and release this data structure.

Possible return values:
  • NBI_SUCCESS: successful call, the NBI_Store  is returned in the store parameter.
  • NBI_ERROR_BAD_PARAMETER: the provided array is NULL or there are errors found decoding the array.

*Note: functions will encode/decode the place inside a store and there is no need for the user to apply NBI_PlaceToByteArray in addition.

REQUEST HANDLING FUNCTIONS

All APIs that require an asynchronous connection to the NavBuilder server to request data use an NBI_Request that can be created calling the appropriate functions. All requests are submitted, handled and destroyed using the following functions.

NBI_RequestCancel
NBI_RequestDestroy
NBI_RequestInProgress
NBI_RequestStart

NBI_RequestCancel

The NBI_RequestCancel function is used to cancel a request in progress when the result is no longer needed.

NBI_Error NBI_RequestCancel ( NBI_Request* request )

Type

Name

Description

NBI_Request*

request

NBI request with one of the request creation functions.

Possible return values:
  • NBI_SUCCESS: successful call, request canceled.
  • NBI_INVALID_REQUEST: the request is null or is no longer pending.
NBI_RequestDestroy

The NBI_RequestDestroy function is used to release the object previously created using one of the NBI_xxRequestCreatexx functions.

NBI_Error NBI_RequestDestroy ( NBI_Request* request )

Type

Name

Description

NBI_Request*

request

NBI request created with one of the request creation functions.

Possible return values:
  • NBI_SUCCESS: successful call, handler object released.
  • NBI_INVALID_REQUEST: the request parameter is null.
NBI_RequestInProgress

The NBI_RequestInProgress function is used to retrieve the status of the request. If the function returns NBI_SUCCESS, then the inProgress parameter is TRUE if the request is in progress.

NBI_Error NBI_RequestInProgress (
  NBI_Request* request ,
  Boolean* inProgress )

Type

Name

Description

NBI_Request*

request

NBI request created with one of the request creation functions.

boolean*

inProgress

If the call succeeds, then this output parameter is TRUE if the request is in progress.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_INVALID_REQUEST: the request parameter is null or contains bad data.
NBI_RequestStart

The NBI_RequestStart function is used to submit the request to the server. When the reply from the server is received, the callback function will be called with an NBI_Information block as a parameter. Individual functions will be called to extract the appropriate information for each type of query.

Note: It is the application's responsibility to release the NBI_Information object with a call to NBI_InformationDestroy().

typedef void (CALLBACK* NBI_RequestCallback) (
  void* appData , 
  NBI_Request* request , 
  NBI_Information* information , 
  NBI_Error error );

NBI_Error NBI_RequestStart (
  NBI_Request* request , 
  NBI_RequestCallback callback ,
  void* applicationData )

Type

Name

Description

NBI_Request*

request

NBI request created with one of the request creation functions.

NBI_RequestCallback

callback

Pointer to the callback for this request. See above for the callback definition.

void*

applicationData

Application context data passed to the callback.

Possible return values:
  • NBI_SUCCESS: successful call, request submitted.
  • NBI_INVALID_CALLBACK: the callback parameter is null.
  • NBI_INVALID_REQUEST: the request parameter is null or contains bad data.

GEOCODING (DEPRECATED)

The Geocoding API enables the application to get the coordinates of a location.
The Geocoding request can take different parameters:

  • A structured address, where fields are passed separately.
  • A free form address, where a single string is used for the entire address.
  • An airport code (3 letters).
  • An intersection of two streets.

The result of a Geocode request is essentially a database match. As such, it can be a single perfect match, a list of partial matches, or no match at all. To handle the possible different results, the geocoding functions provide a way to specify a slice size (telling the server how many results to request) and request additional slices if needed.

REQUEST CREATION FUNCTIONS

The Geocoding API provides request creation functions for each case described above.

NBI_GeocodeRequestCreateAddress
NBI_GeocodeRequestCreateAirport
NBI_GeocodeRequestCreateFreeForm
NBI_GeocodeRequestCreateIntersection

NBI_GeocodeRequestCreateAddress

The NBI_GeocodeRequestCreateAddress function takes an address structure and creates an NBI_Request object that can be submitted using the NBI_RequestStart function.

NBI_Error NBI_GeocodeRequestCreateAddress (
  NBI_Context* context , 
  NBI_Address* address ,
  uint32 sliceSize ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_Address*

address

Structure containing the address to Geocode.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum is 20).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains a new NBI_Request object.
  • NBI_INVALID_ADDRESS: the address parameter is not correctly formed.
NBI_GeocodeRequestCreateAirport

The NBI_GeocodeRequestCreateAirport function takes an airport name or a three-letter airport code and creates an NBI_Request object that can be submitted using the NBI_RequestStart function.

NBI_Error NBI_GeocodeRequestCreateAirport (
  NBI_Context* context ,
  const char* airport ,
  uint32 sliceSize ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

const char*

airport

Airport name or a three-letter airport code.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum is 20).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains a new NBI_Request object.
  • NBI_INVALID_AIRPORT: the airport parameter is invalid.
NBI_GeocodeRequestCreateFreeForm

The NBI_GeocodeRequestCreateFreeForm function takes a string containing a free form query and a string containing a country name and creates an NBI_Request object that can be submitted using the NBI_RequestStart function.

NBI_Error NBI_GeocodeRequestCreateFreeForm (
  NBI_Context* context ,
  const char* freeform , 
  const char* country , 
  uint32 sliceSize ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

const char*

freeform

Free-form address to Geocode.

const char*

country

Country where the Geocode is performed (defaults to USA if blank).

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum is 20).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contain a new NBI_Request object.
  • NBI_INVALID_FREEFORM: the freeform parameter is invalid.
  • NBI_INVALID_COUNTRY: the country parameter is invalid.
NBI_GeocodeRequestCreateIntersection

The NBI_GeocodeRequestCreateIntersection function takes an address structure and a string containing an intersecting street name and creates a Request object that can be submitted using the NBI_RequestStart function.

NBI_Error NBI_GeocodeRequestCreateIntersection (
  NBI_Context* context ,
  NBI_Address* address ,
  const char* crossStreet , 
  uint32 sliceSize , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure created using NBI_ContextCreate.

NBI_Address*

address

NBI structure containing an address (the street number is ignored if present).

const char*

crossStreet

Street name used as the intersecting street to the street specified in the NBI_Address structure.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum is 20).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains a new NBI_Request object.
  • NBI_INVALID_ADDRESS: the address parameter is not correctly formed.
  • NBI_INVALID_CROSSSTREET: the crossStreet parameter is invalid.

REVERSE GEOCODING

The Reverse Geocoding APIs enable the application to provide a coordinate pair and obtain the matching address.

The result of a Reverse Geocode request is the closest matching address to the map coordinate pair. Depending on the location, the results can be a street address with or without a number, or if there are no streets nearby, it can return just a ZIP Code or an area name.

REQUEST CREATION FUNCTIONS

The Reverse Geocoding API provides the following request creation functions.

NBI_ReverseGeocodeRequestCreate 

NBI_ReverseGeocodeRequestCreate

The NBI_ReverseGeocodeRequestCreate function is used to create the ReverseGeocodeRequest object.

NBI_Error NBI_ReverseGeocodeRequestCreate (
  NBI_Information* information,
  double latitude , 
  double longitude , 
  boolean routable ,
  NBI_Request** request )

Type

Name

Description

NBI_Information*

information

Information structure returned by the NBI_Request callback.

double

latitude, longitude

Coordinate pair to find the closest  matching address.

Boolean

routable

If TRUE, return the closest address to which a route can be created.

NBI_Request**

request

NBI_Request structure used to process this query.

If routable is TRUE, the query returns a routable address, which may not be the closest address to the map coordinate pair.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contain the NBI_ReverseGeocodeRequest object.
  • NBI_INVALID_LOC: the requested location is not a valid coordinate pair.

SEARCH (DEPRECATED)

All search functions will be moved to SearchKit.

The Search APIs enable the application to search around a location for supported information:

  • Business search/Points of Interest (POI)
    • By free form
    • By POI category
  • Traffic incidents
  • Gas prices
  • Theaters and movies
  • Events and venues
  • Weather

The result of a search is a slice of results. The size of the slice is set by the host application, but it is usually 10. Iteration functions are provided to request additional results.

NBI_SearchRequestCreateEvent

The NBI_SearchRequestCreateEvent function is used to create the NBI_Request object to search for an event.

NBI_Error NBI_SearchRequestCreateEvent (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name , 
  const char* categoryCodes[] , 
  int numberOfCategoryCodes ,
  NBI_LocalTime startTime , 
  NBI_LocalTime endTime , 
  NBI_EventRating rating , 
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to use for the search. If NULL, the current map bounding box is used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

const char*

categoryCodes[]

Array of event category codes used to filter the search results. See appendix for the list of supported category codes.

int

numberOfCategoryCodes

Number of items in the categoryCodes array.

NBI_LocalTime

startTime

Events starting after this time.

NBI_LocalTime

endTime

Events starting before this time.

NBI_EventRating

rating

Events matching this rating.

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_ERROR_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreateEventVenue

The NBI_SearchRequestCreateEventVenue function is used to create the NBI_Request object to search for an event venue.

NBI_Error NBI_SearchRequestCreateEventVenue (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name , 
  const char* categoryCodes[ ] , 
  int numberOfCategoryCodes ,
  NBI_LocalTime startTime , 
  NBI_LocalTime endTime , 
  NBI_EventRating rating , 
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to use for the search. If NULL, the current map bounding box is used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

const char*

categoryCodes[ ]

Array of event category codes used to filter the search results. See appendix for the list of supported category codes.

int

numberOfCategoryCodes

Number of items in the categoryCodes array.

NBI_LocalTime

startTime

Events starting after this time.

NBI_LocalTime

endTime

Events starting before this time.

NBI_EventRating

rating

Events matching this ratings.

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreateFuel

The NBI_SearchRequestCreateFuel function is used to create the NBI_Request object to do a gas station search with gas prices.

NBI_Error NBI_SearchRequestCreateFuel (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name ,
  NBI_FuelSearchType searchType ,
  uint32 sliceSize ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to use for the search. If NULL, the current map bounding box is used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

NBI_FuelSearchType

searchType

Type of fuel to search for.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum 20).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreateMovie

The NBI_SearchRequestCreateMovie function is used to create the NBI_Request object to search for a movie.

NBI_Error NBI_SearchRequestCreateMovie (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name , 
  const char* genreCode[ ] ,
  int numberOfGenreCodes ,
  NBI_LocalTime startTime , 
  NBI_LocalTime endTime , 
  NBI_MovieShowing showing , 
  NBI_MovieSortBy sortBy ,
  uint32 sliceSize ,
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to use for the search. If NULL, the current map bounding box should be used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

const char*

genreCode[ ]

Array of movie genre codes used to filter the search results. Set to Null to search for all genres.

int

numberOfGenreCodes

Number of items in the genreCodes array.

NBI_LocalTime

startTime

Look for movies starting after this time.

NBI_LocalTime

endTime

Look for movies starting before this time.

NBI_MovieShowing

showing

Used to filter the results (see enumeration)

NBI_MovieSortBy

sortBy

Requested sort type.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum 20).

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains the new NBI_Request object.
  • NBI_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreateMovieTheater

The NBI_SearchRequestCreateMovieTheater function is used to create the NBI_Request object to search for a movie theater.

NBI_Error NBI_SearchRequestCreateMovieTheater (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name ,
  NBI_LocalTime startTime , 
  NBI_LocalTime endTime ,
  uint32 sliceSize ,
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to search for theater s. If NULL, the current map bounding box is used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

NBI_LocalTime

startTime

Look for movies starting after this time.

NBI_LocalTime

endTime

Look for movies starting before this time.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum 20).

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreatePOI

The NBI_SearchRequestCreatePOI function is used to create the NBI_Request object to search for a POI.

NBI_Error NBI_SearchRequestCreatePOI (
  NBI_Context* context , 
  NBI_SearchRegion region ,
  const char* name , 
  const char* categoryCodes[ ] ,
  int numberOfCategoryCodes,
  uint32 sliceSize ,
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchRegion

region

Region to use for the search. If NULL, the current map bounding box is used.

const char*

name

Optional POI name used to filter the results. Can be left blank.

const char*

categoryCodes[ ]

Array of POI category codes used to filter the search results. See appendix for the list of supported POI category codes.

int

numberOfCategoryCodes

Number of items in the categoryCodes array.

uint32

sliceSize

Maximum number of results to return with each request (default is 10, maximum 20).

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_REGION: the requested region is invalid.
NBI_SearchRequestCreateSubSearch

The NBI_SearchRequestCreateSubSearch function is used to create the NBI_Request object to do a sub search.

NBI_Error NBI_SearchRequestCreateSubSearch ( 
  NBI_Context* context , 
  NBI_Information* information ,
  uint32 resultsIndex ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_Information*

information

NBI_Information structure that was returned by the NBI_Request callback.

uint32

resultsIndex

Index to the element in the previous search for which the sub search is requested.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_INFORMATION: the information parameter is NULL.
NBI_SearchRequestCreateWeather

The NBI_SearchRequestCreateWeather function is used to create the NBI_Request object to search for weather.

NBI_Error NBI_SearchRequestCreateWeather (
  NBI_Context* context , 
  NBI_Coordinates* center , 
  NBI_POIExtendedConfiguration extendedConfiguration , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_Coordinates*

center

Coordinates to use as the center of the search area.

NBI_POIExtendedConfiguration

extendedConfiguration

Parameter used to request extended features such as premium placement, enhanced POIs, and formatted text.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_INVALID_COORDINATES: the requested center is NULL.

DIRECTIONS

The Directions API enables the host application to provide an origin and a destination and get detailed directions to go there. The result of the directions query is a NBI_Directions data structure that contains a list of maneuvers that can be formatted for display in any way desired and information that can be used to create the route layer and resize the map to show it. Each maneuver also contains information that can be passed to the Map object to display the maneuver on the map.

REQUEST CREATION FUNCTIONS

The Directions API provides request creation functions for each one of the cases described above.

NBI_RouteRequestCreate 

NBI_RouteRequestCreate

The NBI_RouteRequestCreate function is used to create an NBI_Request structure using an origin and a destination to request directions and construct a route map overlay.

NBI_Error NBI_RouteRequestCreate (
  NBI_Context* context , 
  NBI_Place* origin , 
  NBI_Place* destination , 
  NBI_RouteOptions* options , 
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_Place*

origin

Origin of the route.

NBI_Place*

destination

Destination of the route.

NBI_RouteOptions*

options

Structure used to specify the desired route options.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains the route request parameters.
  • NBI_ERROR:

MOBILE COUPONS (DEPRECATED)

Moved to SearchKit.

The NBI Mobile coupons API provides an aggregation service for various types of mobile coupons provided by different companies with different APIs.

The API is designed to be a superset of the various APIs available and will be expanded as needed in future releases to accommodate new functionality as it becomes available from the coupon providers.

REQUEST CREATION FUNCTIONS

The Mobile Coupons API provides the following request creation functions.

Note: The NBI_StoreRequestCreate and NBI_CouponRequestCreate functions use search filters to pass arbitrary parameters to the search engine. See section 2.8.22 for valid values.

NBI_StoreRequestCreate
NBI_CouponRequestCreate
NBI_ImageRequestCreate
NBI_CategoryListRequestCreate

NBI_StoreRequestCreate

The NBI_StoreRequestCreate function takes several parameters and creates an NBI_Request object that can be submitted using the NBI_RequestStart function.

This query finds all the nearby stores that meet specific criteria – categories, search-terms (keywords). Alternatively, the search can be performed without any specified criteria at all. All criteria is added to the searchFilter element using the provided utility functions.

Note: to load a previously saved store, set an entry in the search filter containing ("store_name", "<store.name>").

NBI_Error NBI_StoreRequestCreate (
  NBI_Context* context ,
  NBI_SearchFilter* searchFilter ,
  const NBI_SearchRegion* searchRegion ,
  uint32 sliceSize ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchFilter*

searchFilter

List of key-value pairs that contains all data used by the API to filter query data.

const NBI_SearchRegion*

searchRegion

Mobile coupon search region.

uint32

sliceSize

Maximum number of results to return with each request.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_ERROR:
NBI_CouponRequestCreate

The NBI_CouponRequestCreate function takes several parameters and creates an NBI_Request object that can be submitted using the NBI_RequestStart function.

This query finds all the coupons/deals, which meet specific criteria – categories, search-terms (keywords). Alternatively, the search can be performed without any specified criteria.

Note: to load a previously saved coupon, set an entry in the search filter containing ("coupon_id", "<coupon.id>").

NBI_Error NBI_CouponRequestCreate (
  NBI_Context* context ,
  NBI_SearchFilter* searchFilter ,
  const NBI_SearchRegion* searchRegion ,
  uint32 sliceSize ,
  NBI_Request** request)

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

NBI_SearchFilter*

searchFilter

List of key-value pairs that contain all data used by the API to filter the query data.

const NBI_SearchRegion*

searchRegion

Mobile coupon search region.

uint32

sliceSize

Maximum number of results to return with each request.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_ERROR:
NBI_ImageRequestCreate

The NBI_GetImageRequestCreate function takes an image ID from a NBI_MobileCoupon and retrieves the image corresponding to it, and delivers it to the client.

NBI_Error NBI_GetImageRequestCreate (
  NBI_Context * context ,
  const char* coupon_img_id ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

const char*

coupon_img_id

Loyalty program card.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_ERROR:
NBI_CategoryListRequestCreate

The NBI_GetCategoryListRequestCreate function uses an optional location, a broad category, and a sub-category to create an NBI_Request object that can be submitted using the NBI_RequestStart function to request lists of broad categories, categories, and sub-categories for the current location:

  • If the location is specified, the resulting lists are limited to what is available nearby. Otherwise, categories for the entire deals database are returned.
  • To get the list of broad categories, leave both parameters NULL.
  • To get a list of categories under a broad category, pass the broad category and leave the category field NULL.
  • To get a list of sub-categories, pass a broad category and a category in the parameters. The category must correspond to the broad category, or the resulting list will be empty.

NBI_Error NBI_GetCategoryListRequestCreate(
  NBI_Context* context ,
  const NBI_SearchRegion* searchRegion ,
  char* broadCategory ,
  char* category ,
  NBI_Request** request )

Type

Name

Description

NBI_Context*

context

Context structure previously created using NBI_ContextCreate.

const NBI_SearchRegion*

searchRegion

Search region for the request.

char*

broadCategory

Broad category for coupons/deals.

char*

category

Category for coupon/deals.

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, request contains the new NBI_Request object.
  • NBI_ERROR:

INFORMATION FUNCTIONS

NBI_InformationCreateIteration

The NBI_InformationCreateIteration function is used to obtain additional search results when there are more results than those returned in the original operation.

NBI_Error NBI_InformationCreateIteration (
  NBI_Information* information , 
  NBI_IterationCommand command , 
  NBI_Request** request )

Type

Name

Description

NBI_Information*

information

Structure returned as a result of a previous request.

NBI_IterationCommand

command

Command to perform (previous/next).

NBI_Request**

request

NBI_Request structure used to process this query.

Possible return values:
  • NBI_SUCCESS: successful call, parameters contains a new NBI_Request object.
  • NBI_INVALID_PARAMETER: at least one of the parameters is invalid.
  • NBI_INVALID_COMMAND: the command parameter is invalid.
NBI_InformationDestroy

The NBI_InformationDestroy function is used to destroy a previously created NBI_Information object. It is the responsibility of the application to call this function to release the NBI_Information returned from a successful NBI_Request.

NBI_Error NBI_InformationDestroy (
  NBI_Information* information )

Type

Name

Description

NBI_Information*

context

Information structure returned by the NBI_Request callback.

Possible return values:
  • NBI_SUCCESS: successful call, the object is destroyed.
  • NBI_INVALID_INFORMATION: the information parameter is invalid.
NBI_InformationSearchFreeResultData

The NBI_InformationSearchFreeResultData function is used to free partial or all search data associated with the POI instance. It can be called after each download/slice, or when search data is no longer needed.

All data is freed automatically after the NB_Information instance is destroyed.

NBI_Error NBI_InformationSearchFreeResultData (
  NBI_Information* information ,
  boolean freeExtendedPlaces )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

boolean

freeExtendedPlaces

If TRUE, the extended places structures in the current slice are freed.

Possible return values:
  • NBI_SUCCESS: successful call, the requested data is freed.
  • NBI_INVALID_INFORMATION: the information parameter is invalid.
NBI_InformationGetEvent (DEPRECATED)

Moved to SearchKit

The NBI_InformationGetEvent function is used to retrieve event data from a search.

NBI_Error NBI_InformationGetEvent (
  NBI_Information* information ,
  int resultIndex , 
  int eventIndex ,
  NBI_Event* event )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

int

resultIndex

Zero-based index of the result to retrieve in this slice; which must be less than the difference between the end and start indices returned by NBI_InformationGetSliceInformation().

int

eventIndex

Index of event in the events array for this result.

NBI_Event*

event

Pointer to a structure to be overwritten with the detailed event information for the requested item.

To retrieve detailed event information (formatted text) call NBI_InformationGetFormattedContentText() and pass the 'contentHandle' from the NB_Event structure.

Possible return values:
  • NBI_SUCCESS: successful call, details has the optional fuel price information.
  • NBI_ERROR:
NBI_InformationGetEventSummary (DEPRECATED)

Moved to SearchKit

The NBI_InformationGetEventSummary function is used to retrieve event summary information from the current POI search.

NBI_Error NBI_InformationGetEventSummary (
  NBI_Information* information ,
  int index, 
  NBI_SummaryResult* summaryResult )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

int

index

Index of the item to retrieve.

NBI_SummaryResult*

summaryResult

Pointer to a structure that to be overwritten with the event summary information for the requested item.

Possible return values:
  • NBI_SUCCESS: successful call, eventSummary has the event summary information for the requested item.
  • NBI_ERROR:
NBI_InformationGetFormattedTextContent (DEPRECATED)

Moved to SearchKit.

The NBI_InformationGetFormattedTextContent function is used to retrieve formatted text for the specified POI. Pass a pointer to a callback function to retrieve the formatted extended place content. This function blocks until all event content is retrieved by the callback function.

typedef void (CALLBACK* NBI_FormattedTextCallback) (
  NBI_Font font , 
  NBI_Color color , 
  const char* text , 
  boolean newline , 
  void* userData );

NBI_Error NBI_InformationGetFormattedTextContent (
  NBI_Information* information,
  NBI_ContentID contentHandle,
  NBI_FormattedTextCallback callback ,
  void* userData )

Type

Name

Description

NBI_Information*

information

Information structure returned from the request.

NBI_ContentID

contentHandle

contentHandle field in the NBI_Event structure returned from the event search.

NBI_FormattedTextCallback

callback

Function called with the formatted content text.

void*

userData

Application context passed to the callback function.

Possible return values:
  • NBI_SUCCESS: successful call, the callback function retrieved the formatted text content.
  • NBI_ERROR:
NBI_InformationGetFuelDetails (DEPRECATED)

Moved to SearchKit.

The NBI_InformationGetFuelDetails function is used to retrieve optional fuel price information from a search. Call this function if NBI_InformationGetResultType returns the type NBI_SRT_FuelDetails. 

It is the responsibility of the host application to allocate and release the memory associated with the NBI_FueldDetails structure.

NBI_Error NBI_InformationGetFuelDetails (
  NBI_Information* information ,
  int resultIndex ,
  NBI_FuelDetails* details )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

int

resultIndex

Index of the item to retrieve.

NBI_FuelDetails*

details

Pointer to a structure to be overwritten with the detailed information for the requested item.

Possible return values:
  • NBI_SUCCESS: successful call, details contains optional fuel price information.
  • NBI_ERROR:
NBI_InformationGetFuelSummary (DEPRECATED)

Moved to SearchKit.

The NBI_InformationGetFuelSummary function is used to retrieve summary fuel price information from the current search. Call this function if NBI_InformationGetResultType returns the type NBI_SRT_FuelSummary. The fuel price information is always based on one downloaded slice.

It is the responsibility of the host application to allocate and release the memory associated with the NBI_FuelSummary structure.

NBI_Error NBI_InformationGetFuelSummary (
  NBI_Information* information , 
  NBI_FuelDetails* fuelSummary )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_FuelDetails*

fuelSummary

Pointer to a structure that to be overwritten with the summary information for the fuel search.

Possible return values:
  • NBI_SUCCESS: successful call, fuelSummary has the fuel price information.
  • NBI_ERROR:
NBI_InformationGetLocation

The NBI_InformationGetLocation function is used to extract a location from the NBI_Information object. This function is usually called after finishing a Geocoding or ReverseGeocoding request.

Note: It is the responsibility of the host application to allocate and release the memory associated with the NBI_MapLocation structure.

NBI_Error NBI_InformationGetLocation (
  NBI_Information* information,
  uint32 index ,
  NBI_MapLocation* location )

Type

Name

Description

NBI_Information*

information

Information structure returned by the NBI_Request callback.

uint32

index

Index of the location to retrieve from the results slice.

NBI_MapLocation*

location

Structure containing the Geocode result (a location) at the specified index. 
Note: It is the responsibility of the application to allocate the memory for the result.

Possible return values:
  • NBI_SUCCESS: successful call, location contains the result from the result at position index in the slice.
  • NBI_INVALID_INDEX: the index parameter is out of bounds.
  • NBI_INVALID_INFORMATION: the information parameter is invalid.
NBI_InformationGetManeuverList

The NBI_InformationGetManeuverList function is used to get the result of the previous route request. Route maneuvers are presented as an array of NBI_Maneuver structures. Each structure contains information for an individual route maneuver.

The NBI_Maneuver structure provides the following information:

  • A unique ID that identifies the maneuver.
  • A string with the maneuver description, which is intended to be shown on a maneuver list view. This string contains text describing the maneuver (i.e.: "TURN LEFT on Palm Ave.").
  • A routing icon code, which can be used to obtain the routing icon image for the maneuver list view.
  • The distance in meters from the previous maneuver.

It is up to the host application to decide how to present this information to the user. The recommended format is a list of maneuvers with each maneuver shown as:

<Icon>                    <Maneuver description>
                                 <Distance>

NBI_Error NBI_InformationGetManeuverList (
  NBI_Information* information , 
  NBI_ManeuverList** maneuvers )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_ManeuverList**

maneuvers

Data structure containing the route ID and an array of maneuvers.

Possible return values:
  • NBI_SUCCESS: successful call, maneuvers contains the directions for the previous route request.
  • NBI_INVALID_HANDLER: the handlers is null or invalid.
NBI_InformationGetRouteOrigin

The NBI_InformationGetRouteOrigin function is used to get the origin point from the previous route request.

NBI_Error NBI_InformationGetRouteOrigin (
  NBI_Information* information,
  NBI_Place* origin )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_Place*

origin

The place for the route's origin point.

Possible return values:
  • NBI_SUCCESS: successful call, origin contains the origin point from the previous route request.
  • NBI_INVALID_HANDLER: the handler is null or invalid.
NBI_InformationGetRouteDestination

The NBI_InformationGetRouteDestination function is used to get the destination point from the previous route request.

NBI_Error NBI_InformationGetRouteDestination (
  NBI_Information* information,
  NBI_Place* destination )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_Place*

destination

Place for the route's destination point.

Possible return values:
  • NBI_SUCCESS: successful call, destination contains the destination point from the previous route request.
  • NBI_INVALID_HANDLER: the handler is null or invalid.
NBI_InformationGetNumberOfEvents (DEPRECATED)

Moved to SearchKit

The NBI_InformationGetNumberOfEvents function retrieves the number of events from the results of an event search.

NBI_Error NBI_InformationGetNumberOfEvents (
  NBI_Information* context ,
  int* resultIndex )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

int*

resultIndex

Zero-based index of the result to retrieve from this slice; which must be less than the difference between the end and start indices returned by NBI_InformationGetSliceInformation().

Possible return values:
  • The number of events available at the specified index value.
NBI_InformationGetPlace (DEPRECATED)

The NBI_InformationGetPlace function retrieves place details from a specific result of a search operation. Call this function if NBI_InformationGetResultType returns the type NBI_SRT_Place.

It is the responsibility of the host application to allocate and release memory associated with the NBI_Place structure. The extended place structure (if requested) is allocated by this function and NBI_InformationFreeResultData() must be called to free data.

NBI_Error NBI_InformationGetPlace ( 
  NBI_Information* information ,
  int resultIndex ,
  NBI_Place* place ,
  double* distance ,
  NBI_ExtendedPlaceData* extendedPlace )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

int

resultIndex

Index of the item to retrieve.

NBI_Place*

place

Pointer to a structure to be overwritten with the requested POI place.

double*

distance

Distance from the POI to the center of the search area. Pass NULL if not needed.

NBI_ExtendedPlaceData*

extendedPlace

Pointer to structure allocated by caller to receive information. The caller can pass NULL if not needed.
Note: if this information is received, its sub-fields can be released by calling NBI_InformationSearchFreeResultData.

Possible return values:
  • NBI_SUCCESS: successful call, extendedPlace contains place details information.
  • NBI_INVALID_INDEX: an invalid index was specified.
  • NBI_ERROR:
NBI_InformationGetResultType (DEPRECATED)

Moved to SearchKit

The NBI_InformationGetResultType function retrieves the type of results of the current POI search operation. This function must be called after NBI_RequestStart () to check what type of information was returned by the POI search. Multiple types can be returned. See NBI_InformationResultType to decide which function to call to retrieve the information. The returned type is based on the current results slice.

NBI_Error NBI_InformationGetResultType (
  NBI_Information* information,
  uint32* typeFlags )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

uint32*

typeFlags

Output parameter containing the available result types for the POI search operation associated with the information parameter. The flags are OR'd from the values in the enumeration NBI_InformationResultType.

Possible return values:
  • NBI_SUCCESS: successful call, type has the result type.
  • NBI_ERROR:
NBI_InformationGetResultCount

The NBI_InformationGetResultCount function is used to manage the slice for additional results.

NBI_Error NBI_InformationGetResultCount ( NBI_Information* information )

Type

Name

Description

NBI_Information*

information

Information structure returned by the NBI_Request callback.

Possible return values:
Returns the number of results available for the request.
NBI_InformationHasMoreResults

The NBI_InformationHasMoreResults function is used to manage the slice for additional results.

boolean NBI_InformationHasMoreResults ( NBI_Information* information )

Type

Name

Description

NBI_Information*

information

Information structure returned by the NBI_Request callback.

Possible return values:
  • non-zero: more results are available for the request.
  • 0: there are no additional results.
NBI_InformationGetWeather (DEPRECATED)

Moved to SearchKit

The NBI_InformationGetWeather function retrieves weather information from the current search operation. This function does not use an index like other search result functions because there is only one result per weather search. Call NBI_InformationGetPlace() with index zero to retrieve the place for which the weather information applies.

NBI_Error NBI_InformationGetWeather (
  NBI_Information* information , 
  NBI_WeatherConditions* conditions , 
  NBI_WeatherForecasts* forecast )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_WeatherConditions*

conditions

Output parameter containing weather conditions for the weather search associated with the information parameter.

NBI_WeatherForecasts*

forecast

Output parameter containing weather forecasts for the weather search associated with the information parameter.

Possible return values:
  • NBI_SUCCESS: successful call, type has the result type.
  • NBI_ERROR:
NBI_InformationManeuverListDestroy

The NBI_InformationManeuverListDestroy function releases the memory associated with the NBI_ManeuverList structure returned from NBI_InformationGetManeuverList.

NBI_Error NBI_InformationManeuverListDestroy (
  NBI_Information* information , 
  NBI_ManeuverList* maneuvers )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_ManeuverList*

maneuvers

Data structure returned from NBI_InformationGetManeuverList.

Possible return values:
  • NBI_SUCCESS: successful call, the object is destroyed.
  • NBI_INVALID_INFORMATION: the information parameter is invalid.
NBI_GetEnrollLoyaltyProgramResult (DEPRECATED)

The NBI_GetEnrollLoyaltyProgramResult function retrieves the result of an enroll loyalty program card request. This function does not use an index like other search result functions because there is only one result per enroll request.

NBI_Error NBI_GetEnrollLoyaltyProgramResult (
  NBI_Information* information ,
  boolean* status ,
  char** description )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

Boolean*

status

Indicates success (true) or failure (false).

char**

description

Optional attribute, providing more information about the status. Eg: "duplicate card owner".
This parameter can be NULL, in which case no value is returned.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_GetUnenrollLoyaltyProgramResult (DEPRECATED)

The NBI_GetUnenrollLoyaltyProgramResult function retrieves the result of an unenroll loyalty program card request. This function does not use an index like the other search result functions because there is only one result per unenroll request.

NBI_Error NBI_GetUnenrollLoyaltyProgramResult (
  NBI_Information* information ,
  boolean* status ,
  char** description )

Type

Name

Description

NBI_Information*

information

NBI_Information returned by the NBI_Request callback.

boolean*

status

Indicates success (true) or failure (false).

char**

description

Optional attribute, providing more information about the status. Eg: "duplicate card owner".
This parameter can be NULL, in which case no value is returned.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_GetClipCouponResult (DEPRECATED)

The NBI_GetClipCouponResult function retrieves the result of clipping a coupon to the loyalty program card (a request that was started using NBI_ClipCouponRequestCreate). This function does not use an index like the other search result functions because there is only one result per coupon clipping request.

NBI_Error NBI_GetClipCouponResult (
  NBI_Information* information ,
  NBI_ClippingStatus* status ,
  char** clippingId )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_ClippingStatus*

status

Status of clipping operation.

char**

clippingId

ID of the clipping (as provided by the coupon service provider). E.g.: “12341234”.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_GetMoveClippingResult (DEPRECATED)

The NBI_GetMoveClippingResult function retrieves the result of moving a clipped coupon (a request that was started using NBI_MoveClippingRequestCreate). This function does not use an index like the other search result functions because there is only one result per move clipping request.

NBI_Error NBI_GetMoveClippingResult (
  NBI_Information* information ,
  NBI_ClippingStatus* status ,
  char** clippingId )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_ClippingStatus*

status

Status of clipping operation.

char**

clippingId

ID of the clipping (as provided by the coupon service provider). E.g.: "12341234".

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_GetLoyaltyProgramCard (DEPRECATED)

The NBI_GetLoyaltyProgramCard function retrieves the loyalty program card.

NBI_Error NBI_GetLoyaltyProgramCard (
  NBI_Information* information ,
  NBI_LoyaltyProgramCard* programCard ,
  int resultIndex )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_LoyaltyProgramCard*

programCard

Loyalty program card.

int

resultIndex

Index of the item to retrieve.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_InformationGetStore (DEPRECATED)

The NBI_InformationGetStore function retrieves a store. This function retrieves store data from a request created using NBI_StoreRequestCreate.

NBI_Error NBI_InformationGetStore (
  NBI_Information* information ,
  NBI_Store** store ,
  int resultIndex )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_Store**

store

Store name.

int

resultIndex

Index of the item to retrieve.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_InformationGetStoreCoupons (DEPRECATED)

The NBI_InformationGetStoreCoupons function retrieves a store with associated coupons. This function retrieves store and coupon data from a request created using NBI_CouponRequestCreate.

Depending on the way the query was created, the server may return one full store object and one full coupon object, a partial store object and a full coupon object, or a full store object with no coupons.

NBI_Error NBI_InformationGetStoreCoupons (
  NBI_Information* information ,
  NBI_Store** storeCoupons ,
  int resultIndex )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBI_Store**

storeCoupons

Store with associated coupons.

int

resultIndex

Index of the item to retrieve.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_InformationGetImage (DEPRECATED)

The NBI_InformationGetImage function retrieves coupon images associated with a coupon.

NBI_Error NBI_InformationGetImage (
  NBI_Information* information , 
  NBI_Image * image )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

NBIImage*

image

Coupon image.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:
NBI_InformationGetCategoryList

The NBI_InformationGetCategoryList function retrieves the result of a request submitted using the NBI_GetCategoryListRequestCreate. The category list is returned as three arrays of strings and the caller is responsible for releasing memory when done with them.

Depending on the search request, the possible results are:

  • A list of broad categories, no categories, and no sub-categories.
  • A single broad category, a list of categories, and no sub-categories.
  • A single broad category, a single category, and a list of sub-categories.
  • Three empty lists (no matches).

NBI_Error NBI_InformationGetCategoryList (
  NBI_Information* information ,
  char** broad_categories[ ] ,
  int numBroadCategories ,
  char** categoryList[ ] ,
  int numCategories ,
  char** subCategories[ ] ,
  int numSubCategories )

Type

Name

Description

NBI_Information*

information

NBI_Information structure returned by the NBI_Request callback.

char**

broadCategoryList[ ]

List of broad categories.

int

numBroadCategories

Number of entries in the broad categories list.

char**

categoryList[ ]

List of categories.

int

numCategories

Number of entries in the categories list.

char**

subCategoryList[ ]

List of sub-categories.

int

numSubCategories

Number of entries in the sub-categories list.

Possible return values:
  • NBI_SUCCESS: successful call.
  • NBI_ERROR:

DEVICE-SPECIFIC API

Platform-specific APIs are generated automatically from NBI code using Doxygen (on C platforms) and Javadoc (on Java platforms) and made available on the NBI web documentation site.