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.

DATA STRUCTURES

Data Structures
MapKit libraries use a large number of data structures. The following tables show the content of the data structures in a language agnostic fashion. For the actual data types inside each data structure, refer to the platform-specific documentation.
NBI_BoundingBox NBI_Coordinates NBI_ExtendedPlaceData NBI_FuelSummary NBI_Information NBI_MapLocation NBI_Map NBI_OverallRating NBI_PinImage NBI_Rectangle NBI_RouteOptions NBI_Store NBI_TrafficIncident NBI_WeatherForecasts	NBI_Category NBI_Event NBI_FuelDetails NBI_FuelType NBI_Layer NBI_Maneuver NBI_MapConfiguration NBI_Phone NBI_Place NBI_Request NBI_SearchFilter NBI_StoreCoupons NBI_WeatherConditions Data Types	NBI_Context NBI_EventPerformance NBI_FuelProduct NBI_Image NBI_LoyaltyProgramCard NBI_ManeuverList NBI_MobileCoupon NBI_Pin NBI_POIContent NBI_RouteID NBI_SearchRegion NBI_SummaryResult NBI_WeatherForecast

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

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 2zoomLevel 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 2zoomLevel 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 2zoomLevel 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 2zoomLevel 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

The Map Control enables the host application to register to receive events. A series of function calls are provided to enable the host to register to the various events that can be triggered as the user interacts with the map.

NBI_MapBeginUserEventCallback
NBI_MapEndUserEventCallback
NBI_MapSetCenterAndZoomChangeCallback
NBI_MapSetDropPinCallback
NBI_MapSetDroppedPinCallback

NBI_MapSetPaintCallback
NBI_MapSetPinBubbleGetRectangleCallback
NBI_MapSetPinBubbleDrawCallback
NBI_MapSetPinDragEndCallback
NBI_MapSetPinDragRequestCallback

NBI_MapSetPinSelectedCallback
NBI_MapSetPinTouchedCallback
NBI_MapSetPinTrafficBubbleTouchedCallback
NBI_MapSetResizeCallback
NBI_MapSetTrafficVisibleChangeCallback

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

MapKit provides utilities to perform map-related calculations.

NBI_LaunchDealURL
NBI_RecordCouponAnalyticsEvent
NBI_ByteArrayToMobileCoupon
NBI_MapByteArrayToPlace
NBI_MapConvertCoordinatesToMapXY
NBI_MapConvertMapXYToCoordinates

NBI_MapCreateImage
NBI_MapDestroyImage
NBI_MapDestroyByteArray
NBI_MapDistance
NBI_MapFromURL
NBI_MapIsImageReady
NBI_MapGetAPILevel
NBI_MapGetRoutingIconImage

NBI_MapIsNavigationAvailable
NBI_MapNavigateTo
NBI_MapPlaceFromLocation
NBI_MapPlaceToByteArray
NBI_MapResetTileCache
NBI_MapToURL
NBI_MobileCouponToByteArray

NBI_SearchFilterCreate
NBI_SearchFilterAdd
NBI_SearchFilterDestroy
NBI_IsServiceApplicationAvailable
NBI_ServiceApplicationInstallLink
NBI_StoreToByteArray
NBI_ByteArrayToStore

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 widthheightbitmapdepth/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.

REQUEST CREATION FUNCTIONS

The Search API provides the following request creation functions:

NBI_SearchRequestCreateEvent
NBI_SearchRequestCreateEventVenue

NBI_SearchRequestCreateFuel
NBI_SearchRequestCreateMovie
NBI_SearchRequestCreateMovieTheater

NBI_SearchRequestCreatePOI
NBI_SearchRequestCreateSubSearch
NBI_SearchRequestCreateWeather

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
NBI_InformationDestroy
NBI_InformationSearchFreeResultData
NBI_InformationGetEvent
NBI_InformationGetEventSummary
NBI_InformationGetFormattedTextContent
NBI_InformationGetFuelDetails
NBI_InformationGetFuelSummary

NBI_InformationGetLocation
NBI_InformationGetManeuverList
NBI_InformationGetRouteOrigin
NBI_InformationGetRouteDestination
NBI_InformationGetNumberOfEvents
NBI_InformationGetPlace
NBI_InformationGetResultType
NBI_InformationGetResultCount

NBI_InformationHasMoreResults
NBI_InformationGetWeather
NBI_InformationManeuverListDestroy
NBI_GetEnrollLoyaltyProgramResult
NBI_GetUnenrollLoyaltyProgramResult
NBI_GetClipCouponResult
NBI_GetMoveClippingResult
NBI_GetLoyaltyProgramCard

NBI_InformationGetStore
NBI_InformationGetStoreCoupons
NBI_InformationGetImage
NBI_InformationGetCategoryList

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.