6.5.2 GetList

GetList is used to retrieve information about landmarks, landmark categories, or landmark databases. Landmarks and landmark categories are retrieved from the specified landmark database or, if no database is specified, from the default one.

Input parameter specifies what landmark information is returned and how the returned information is sorted.

Name	Type	Range	Description
Type	unicode string	`Landmark` `Category` `Database`	Performs operation based on the specified content types.
[Filter]	map Landmark search criteria: For more information, see Key Values 6.5.8 section in Landmarks. Category search criteria: For more information, see Key Values 6.5.8 section in Landmarks. Database search criteria `[DbProtocol]`: unicode string	Landmark search criteria: It is the map containing the landmark search fields for setting the search criteria. Text Criterion: The following fields can be specified: `LandmarkName` `LandmarkDesc` Nearest Criterion: The following fields need to be specified: `LandmarkPosition` `CoverageRadiusOption` `MaximumDistance` Category Criterion: The following field needs to be specified: `CategoryName` Area Criterion: The following field needs to be specified: `BoundedArea` Category search criteria: It is the map containing the landmark category search fields for setting the search criteria. Database search criteria: `DbProtocol`: Search criteria are the protocol string.	Optional Parameter. If filter is not specified, an iterator to all entries of the specified type is returned. Landmark search criteria: Specify one or more search criteria to retrieve a list of landmarks. `CoverageRadiusOption` and `MaximumDistance` are required only when landmark Position is specified. Category Search Criteria: Specify text with wild cards to iterate through the list of categories. Database Search Criteria: If you do not specify protocol then all available databases will be listed.
[Sort]	map [Key]: unicode string Order: unicode string	Key: Possible Values for the types: Landmark: `LandmarkName` Category: `CategoryName` Database: `DatabaseURI` Order: Ascending Descending	Optional Parameter. Default Value for Order Type Landmarks: Ascending Type Category: None Type Database: Ascending Sorts qualified list based on sort key and sort order.

Output parameters contain the requested information. They also contain ErrorCode, and ErrorMessage if the operation fails.

Name	Type	Range (Type: string)	Description
`ReturnValue`	Iterable To maps of requested type	map: `Landmark` `Category` `Database`	Iterator to the retrieved list of items of the requested type. For map of type, see `Landmark`, `Category`, and `Database` in the Key Values 6.5.8 section.
`ErrorCode`	int	NA	Service specific error code on failure of the operation.
`ErrorMessage`	string	NA	Error description in Engineering English.

Error code value	Description
`-304`	General Error
`0`	Success
`1000`	Invalid service argument
`1002`	Bad argument type
`1003`	Missing argument
`1004`	Service not supported
`1012`	Item not found

Error messages	Description
`Landmarks:GetList:Type is missing`	Indicates Type is missing or data type of Type is mismatched.
`Landmarks:GetList:Type is invalid`	Indicates that Type is not a value in the given range.
`Landmarks:GetList:Data is missing`	Indicates Data is missing or data type of Data is mismatched.
`Landmarks:GetList:LandmarkPosition is missing`	Indicates `LandmarkPostion` is missing or data type of `LandmarkPostion` is mismatched.
`Landmarks:GetList:Latitude is missing`	Indicates Latitude is missing or data type of Latitude is mismatched.
`Landmarks:GetList:Longitude is missing`	Indicates Longitude is missing or data type of Longitude is mismatched.
`Landmarks:GetList:BoundedArea is missing`	Indicates `BoundedArea` is missing or data type of `BoundedArea` is mismatched.
`Landmarks:GetList:NorthLatitude is missing`	Indicates `NorthLatitude` is missing or data type of `NorthLatitude` is mismatched.
`Landmarks:GetList:SouthLatitude is missing`	Indicates `SouthLatitude` is missing or data type of `SouthLatitude` is mismatched.
`Landmarks:GetList:EastLongitude is missing`	Indicates `EastLongitude` is missing or data type of `EastLongitude` is mismatched.
`Landmarks:GetList:WestLongitude is missing`	Indicates `WestLongitude` is missing or data type of `WestLongitude` is mismatched.
`Landmarks:GetList:MaximumMatches is invalid`	Indicates `MaximumMatches` value provided is invalid that is, equal or less than 0.
`Landmarks:GetList:Sort is missing`	Indicates Sort is missing or data type of Sort is mismatched.

The following sample code illustrates how to query a list of Landmarks with search criteria, in asynchronous mode:

import scriptext
import e32

# Using e32.Ao_lock() to make main function wait till callback is hit
lock = e32.Ao_lock()

# Callback function will be called when the requested service is complete
def get_list(trans_id, event_id, input_params):
    if event_id != scriptext.EventCompleted:   
# Check the event status
        print "Error in retrieving required info"
        print "Error code is: " + str(input_params["ReturnValue"]["ErrorCode"])
        if "ErrorMessage" in input_params["ReturnValue"]:
            print "Error message:" + input_params["ReturnValue"]["ErrorMessage"]
    else:
        print "The landmarks are"
        for i in input_params["ReturnValue"]:
            print "Name of Landmark"
            print i["LandmarkName"]
            print "Description of Landmark"
            print i['LandmarkDesc']

    lock.signal()

# Async Query a list of Landmarks with search criteria
landmark_handle = scriptext.load('Service.Landmarks', 'IDataSource')
event_id = landmark_handle.call('GetList', {'Type': u'Landmark',
                                            'Filter': {'uDatabaseURI':u'dataBaseUri',
                                                      'LandmarkName':u'AnyLandMarkNm'},
                                            'Sort': {'Key':u'LandmarkName',
                                                     'Order':u'Descending'}}, 
                                callback=get_list)

print "Waiting for the request to be processed!"
lock.wait()
print "Request complete!"

Interface	`IDataSource`
Description	Retrieves an iterable on items qualified by search criteria.
Response Model	Synchronous and asynchronous, depending on the criteria and use case.
Pre-condition	`IDataSource` interface is loaded.
Post-condition	The iterable points to the first element in the list from an active or specified database. The default or active database opened for reading landmarks and categories. Creates the database, if it does not exist and is set as active.