Place

---

This provides APIs related to Place information, used in Place Discovery and Search.

Functions
int	maps_place_destroy (maps_place_h place)
	Destroys the place handle and releases all its resources.
int	maps_place_clone (const maps_place_h origin, maps_place_h *cloned)
	Clones the place handle.
int	maps_place_get_id (const maps_place_h place, char **id)
	Gets the place ID.
int	maps_place_get_name (const maps_place_h place, char **name)
	Gets the place name.
int	maps_place_get_uri (const maps_place_h place, char **uri)
	Gets the place view URI.
int	maps_place_get_location (const maps_place_h place, maps_coordinates_h *location)
	Gets the place location.
int	maps_place_get_distance (const maps_place_h place, int *distance)
	Gets the place distance from the center of the location.
int	maps_place_get_address (const maps_place_h place, maps_address_h *address)
	Gets the place address.
int	maps_place_get_rating (const maps_place_h place, maps_place_rating_h *rating)
	Gets the place rating.
int	maps_place_foreach_property (const maps_place_h place, maps_place_properties_cb callback, void *user_data)
	Retrieves all properties.
int	maps_place_foreach_category (const maps_place_h place, maps_place_categories_cb callback, void *user_data)
	Retrieves all categories.
int	maps_place_foreach_attribute (const maps_place_h place, maps_place_attributes_cb callback, void *user_data)
	Retrieves all attributes.
int	maps_place_foreach_contact (const maps_place_h place, maps_place_contacts_cb callback, void *user_data)
	Retrieves all contacts.
int	maps_place_foreach_editorial (const maps_place_h place, maps_place_editorials_cb callback, void *user_data)
	Retrieves all editorials.
int	maps_place_foreach_image (const maps_place_h place, maps_place_images_cb callback, void *user_data)
	Retrieves all images.
int	maps_place_foreach_review (const maps_place_h place, maps_place_reviews_cb callback, void *user_data)
	Retrieves all reviews.
int	maps_place_get_supplier_link (const maps_place_h place, maps_place_link_object_h *supplier)
	Gets the place supplier link.
int	maps_place_get_related_link (const maps_place_h place, maps_place_link_object_h *related)
	Gets the place related link.
int	maps_place_list_foreach (const maps_place_list_h place_list, maps_place_cb callback, void *user_data)
	Retrieves all places.
int	maps_place_list_destroy (maps_place_list_h place_list)
	Frees all of the memory used by a place list.
Typedefs
typedef void *	maps_place_h
	The Place handle.
typedef void *	maps_place_list_h
	The Place list handle.
typedef bool(*	maps_place_properties_cb )(int index, int total, char *key, void *value, void *user_data)
	Called when requesting the list of Place Properties.
typedef bool(*	maps_place_categories_cb )(int index, int total, maps_place_category_h category, void *user_data)
	Called when requesting the list of Place Categories.
typedef bool(*	maps_place_attributes_cb )(int index, int total, maps_place_attribute_h attribute, void *user_data)
	Called when requesting the list of Place Attributes.
typedef bool(*	maps_place_contacts_cb )(int index, int total, maps_place_contact_h contact, void *user_data)
	Called when requesting the list of Place Contacts.
typedef bool(*	maps_place_editorials_cb )(int index, int total, maps_place_editorial_h editorial, void *user_data)
	Called when requesting the list of Place Editorial.
typedef bool(*	maps_place_images_cb )(int index, int total, maps_place_image_h image, void *user_data)
	Called when requesting the list of Place Image.
typedef bool(*	maps_place_reviews_cb )(int index, int total, maps_place_review_h review, void *user_data)
	Called when requesting the list of Place Review.
typedef bool(*	maps_place_cb )(int index, maps_place_h place, void *user_data)
	Called when requesting the list of Place.

---

Typedef Documentation

typedef bool(* maps_place_attributes_cb)(int index, int total, maps_place_attribute_h attribute, void *user_data)

Called when requesting the list of Place Attributes.

This callback is invoked while iterating through the list of Place Attributes.

Since :

2.4

Remarks:

attribute is valid only in this function and must be released using maps_place_attribute_destroy().
To use attribute outside this function, clone it with maps_place_attribute_clone().

Parameters:

[in]	index	The current index of attribute
[in]	total	The total amount of attributes
[in]	attribute	The place attribute handle
[in]	user_data	The user data passed from the maps_place_foreach_attribute()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_attribute() will invoke this callback.

See also:

maps_place_foreach_attribute()

maps_place_attribute_h

typedef bool(* maps_place_categories_cb)(int index, int total, maps_place_category_h category, void *user_data)

Called when requesting the list of Place Categories.

This callback is invoked while iterating through the list of Place Categories.

Since :

2.4

Remarks:

category is valid only in this function and must be released using maps_place_category_destroy().
To use category outside this function, clone it with maps_place_category_clone().

Parameters:

[in]	index	The current index of category
[in]	total	The total amount of categories
[in]	category	The place category handle
[in]	user_data	The user data passed from maps_place_foreach_category()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_category() will invoke this callback.

See also:

maps_place_foreach_category()

maps_place_category_h

typedef bool(* maps_place_cb)(int index, maps_place_h place, void *user_data)

Called when requesting the list of Place.

This callback is invoked while iterating through the list of Place.

Since :

3.0

Parameters:

[in]	index	The current index of review
[in]	place	The place handle
[in]	user_data	The user data passed from the maps_place_list_foreach()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_list_foreach() will invoke this callback.

See also:

maps_place_list_foreach()

maps_place_get_id()

maps_place_get_name()

maps_place_get_uri()

maps_place_get_location()

maps_place_get_distance()

maps_place_get_rating()

maps_place_foreach_category()

typedef bool(* maps_place_contacts_cb)(int index, int total, maps_place_contact_h contact, void *user_data)

Called when requesting the list of Place Contacts.

This callback is invoked while iterating through the list of Place Contacts.

Since :

2.4

Remarks:

contact is valid only in this function and must be released using maps_place_contact_destroy().
To use contact outside this function, clone it with maps_place_contact_clone().

Parameters:

[in]	index	The current index of contact
[in]	total	The total amount of contacts
[in]	contact	The place contact handle
[in]	user_data	The user data passed from the maps_place_foreach_contact()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_contact() will invoke this callback.

See also:

maps_place_foreach_contact()

maps_place_contact_h

typedef bool(* maps_place_editorials_cb)(int index, int total, maps_place_editorial_h editorial, void *user_data)

Called when requesting the list of Place Editorial.

This callback is invoked while iterating through the list of Place Editorials.

Since :

2.4

Remarks:

editorial is valid only in this function and must be released using maps_place_editorial_destroy().
To use editorial outside this function, clone it with maps_place_editorial_clone().

Parameters:

[in]	index	The current index of editorial
[in]	total	The total amount of editorials
[in]	editorial	The place editorial handle
[in]	user_data	The user data passed from the maps_place_foreach_editorial()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_editorial() will invoke this callback.

See also:

maps_place_foreach_editorial()

maps_place_editorial_h

typedef void* maps_place_h

The Place handle.

The handle of Place instance.

Since :

2.4

Remarks:

To release the handle use maps_place_destroy().
To clone the handle use maps_place_clone().

See also:

maps_place_destroy()

maps_place_clone()

typedef bool(* maps_place_images_cb)(int index, int total, maps_place_image_h image, void *user_data)

Called when requesting the list of Place Image.

This callback is invoked while iterating through the list of Place Images.

Since :

2.4

Remarks:

image is valid only in this function and must be released using maps_place_image_destroy().
To use image outside this function, clone it with maps_place_image_clone().

Parameters:

[in]	index	The current index of image
[in]	total	The total amount of images
[in]	image	The place image handle
[in]	user_data	The user data passed from the maps_place_foreach_image()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_image() will invoke this callback.

See also:

maps_place_foreach_image()

maps_place_image_h

typedef void* maps_place_list_h

The Place list handle.

The handle of Place list instance.

Since :

3.0

See also:

maps_place_list_foreach()

maps_place_list_destroy()

typedef bool(* maps_place_properties_cb)(int index, int total, char *key, void *value, void *user_data)

Called when requesting the list of Place Properties.

This callback is invoked while iterating through the list of Place Properties.

Since :

2.4

Remarks:

key and value must be released using free() and corresponding release method for property value correspondingly.

Parameters:

[in]	index	The current index of property
[in]	total	The total amount of properties
[in]	key	The key of property
[in]	value	The value of property
[in]	user_data	The user data passed from maps_place_foreach_property()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_property() will invoke this callback.

See also:

maps_place_foreach_property()

typedef bool(* maps_place_reviews_cb)(int index, int total, maps_place_review_h review, void *user_data)

Called when requesting the list of Place Review.

This callback is invoked while iterating through the list of Place Reviews.

Since :

2.4

Remarks:

review is valid only in this function and must be released using maps_place_review_destroy().
To use review outside this function, clone it with maps_place_review_clone().

Parameters:

[in]	index	The current index of review
[in]	total	The total amount of reviews
[in]	review	The place review handle
[in]	user_data	The user data passed from the maps_place_foreach_review()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_place_foreach_review() will invoke this callback.

See also:

maps_place_foreach_review()

maps_place_image_h

---

Function Documentation

int maps_place_clone	(	const maps_place_h	origin,
		maps_place_h *	cloned
	)

Clones the place handle.

This function clones the place handle origin and all its resources.

Since :

2.4

Remarks:

cloned must be released using maps_place_destroy().

Parameters:

[in]	origin	The original place handle
[out]	cloned	A cloned place handle

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_OUT_OF_MEMORY	Out of memory
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

See also:

maps_place_destroy()

int maps_place_destroy

(

maps_place_h

place

)

Destroys the place handle and releases all its resources.

This function destroys the place handle and releases all its resources.

Since :

2.4

Parameters:

[in]

place

The place handle to destroy

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

See also:

maps_place_clone()

int maps_place_foreach_attribute	(	const maps_place_h	place,
		maps_place_attributes_cb	callback,
		void *	user_data
	)

Retrieves all attributes.

This function retrieves all place attributes.

Since :

2.4

Remarks:

The attributes will be delivered via maps_place_attributes_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_attributes_cb() repeatedly to retrieve each attribute.

See also:

maps_place_attributes_cb()

int maps_place_foreach_category	(	const maps_place_h	place,
		maps_place_categories_cb	callback,
		void *	user_data
	)

Retrieves all categories.

This function retrieves all place categories.

Since :

2.4

Remarks:

The categories will be delivered via maps_place_categories_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_categories_cb() repeatedly to retrieve each category.

See also:

maps_place_categories_cb()

int maps_place_foreach_contact	(	const maps_place_h	place,
		maps_place_contacts_cb	callback,
		void *	user_data
	)

Retrieves all contacts.

This function retrieves all place contacts.

Since :

2.4

Remarks:

The contacts will be delivered via maps_place_contacts_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_contacts_cb() repeatedly to retrieve each contact.

See also:

maps_place_contacts_cb()

int maps_place_foreach_editorial	(	const maps_place_h	place,
		maps_place_editorials_cb	callback,
		void *	user_data
	)

Retrieves all editorials.

This function retrieves all place editorials.

Since :

2.4

Remarks:

The editorials will be delivered via maps_place_editorials_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_editorials_cb() repeatedly to retrieve each editorial.

See also:

maps_place_editorials_cb()

int maps_place_foreach_image	(	const maps_place_h	place,
		maps_place_images_cb	callback,
		void *	user_data
	)

Retrieves all images.

This function retrieves all place images.

Since :

2.4

Remarks:

The images will be delivered via maps_place_images_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_images_cb() repeatedly to retrieve each image.

See also:

maps_place_images_cb()

int maps_place_foreach_property	(	const maps_place_h	place,
		maps_place_properties_cb	callback,
		void *	user_data
	)

Retrieves all properties.

This function retrieves all place properties.

Since :

2.4

Remarks:

The properties will be delivered via maps_place_properties_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_properties_cb() repeatedly to retrieve each property.

See also:

maps_place_properties_cb()

int maps_place_foreach_review	(	const maps_place_h	place,
		maps_place_reviews_cb	callback,
		void *	user_data
	)

Retrieves all reviews.

This function retrieves all place reviews.

Since :

2.4

Remarks:

The reviews will be delivered via maps_place_reviews_cb().

Parameters:

[in]	place	The place handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_reviews_cb() repeatedly to retrieve each review.

See also:

maps_place_reviews_cb()

int maps_place_get_address	(	const maps_place_h	place,
		maps_address_h *	address
	)

Gets the place address.

This function gets the place address.

Since :

2.4

Remarks:

address must be released using maps_address_destroy().

Parameters:

[in]	place	The place handle
[out]	address	The place address

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_distance	(	const maps_place_h	place,
		int *	distance
	)

Gets the place distance from the center of the location.

This function gets the place distance from the center of the location.

Since :

2.4

Parameters:

[in]	place	The place handle
[out]	distance	The place distance in meters

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_id	(	const maps_place_h	place,
		char **	id
	)

Gets the place ID.

This function gets the place ID.

Since :

2.4

Remarks:

id must be released using free().

Parameters:

[in]	place	The place handle
[out]	id	The place ID

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_location	(	const maps_place_h	place,
		maps_coordinates_h *	location
	)

Gets the place location.

This function gets the place location.

Since :

2.4

Remarks:

location must be released using maps_coordinates_destroy().

Parameters:

[in]	place	The place handle
[out]	location	The place location

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_name	(	const maps_place_h	place,
		char **	name
	)

Gets the place name.

This function gets the place name.

Since :

2.4

Remarks:

name must be released using free().

Parameters:

[in]	place	The place handle
[out]	name	The place name

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_rating	(	const maps_place_h	place,
		maps_place_rating_h *	rating
	)

Gets the place rating.

This function gets the place rating.

Since :

2.4

Remarks:

rating must be released using maps_place_rating_destroy().

Parameters:

[in]	place	The place handle
[out]	rating	The place rating handle

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_related_link	(	const maps_place_h	place,
		maps_place_link_object_h *	related
	)

Gets the place related link.

This function gets the place related link.

Since :

2.4

Remarks:

related must be released using maps_place_link_object_destroy().

Parameters:

[in]	place	The place handle
[out]	related	The place related link

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_supplier_link	(	const maps_place_h	place,
		maps_place_link_object_h *	supplier
	)

Gets the place supplier link.

This function gets the place supplier link.

Since :

2.4

Remarks:

supplier must be released using maps_place_link_object_destroy().

Parameters:

[in]	place	The place handle
[out]	supplier	The place supplier link

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_get_uri	(	const maps_place_h	place,
		char **	uri
	)

Gets the place view URI.

This function gets the place view URI.

Since :

2.4

Remarks:

uri must be released using free().

Parameters:

[in]	place	The place handle
[out]	uri	The place view URI

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

int maps_place_list_destroy

(

maps_place_list_h

place_list

)

Frees all of the memory used by a place list.

Since :

3.0

Parameters:

[in]

place_list

The place list handle

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_SUPPORTED	Not supported

See also:

maps_place_list_foreach()

int maps_place_list_foreach	(	const maps_place_list_h	place_list,
		maps_place_cb	callback,
		void *	user_data
	)

Retrieves all places.

This function retrieves all places.

Since :

3.0

Remarks:

The places will be delivered via maps_place_cb().
place_list must be released using maps_place_list_destroy().

Parameters:

[in]	place_list	The place list handle
[in]	callback	The callback function to invoke
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_NOT_SUPPORTED	Not supported

Postcondition:

This function invokes maps_place_cb() repeatedly to retrieve each place.

See also:

maps_place_cb()

maps_place_list_destroy()