2   Requests

The .in file

A request is a textfile (ASCII) with the file extension ".in". The application reads and parses the .in file when it's placed in the directory "\My Documents\tb-navi.remote\" on the mobile device or “C:\Document and Settings\All Users\Application Data\map&guide navigator\remote\” on Windows XP or “C:\ProgramData\map&guide navigator\remote\” on a Windows 7 PC. The result of the request (return-values, errors, ...) is written after execution in a text file with the same name and the extension ".out" in the same directory as the .in file. .in file.

Every .in file and .out file contains two types of elements:

• Section element: A section element groups one or more attribute elements.
  Syntax: [section-name]
  Every .in and .out file has to contain a [Head] section, where common attributes are specified. Depending on the type of request, there may be request-specific sections in the .in and .out file.
• Attribute element: Attributes define the behaviour of a request.
  Syntax: attribute-key=attribute-value.
  Don't put spaces before and after the equals sign. Only one attribute per line is allowed. Attributes can be either compulsory or optional. A missing required attribute results in a non-execution of the request and a corresponding error-description in the .out file.

Attributes in [Head] section:

• Type: Type of request.
  The values for the different requests can be found in the corresponding page for each request in this documentation.
• Blocking:

  Blocking	Description
  0	Other requests will be executed immediately
  1	Other requests will be executed after this request finished successfully

  The blocking attribute is optional, default value is 0.
  
• Mode:

  Mode	Description
  0	Try once: Execution of this request is tried once, the request will be deleted afterwards
  1	Try until success: The request is executed until it finishes successfully and will then be deleted
  2	Loop: The request is executed in a loop and will not be deleted

  The mode attribute is optional, default value is 0.
  

The .out file

An .out file is generated after the execution of a request. The .out file also contains a [Head] section with the following attributes:

Attributes in [Head] section:

• Type: The Type attribute given in the .in file
• TypeDesc: A textual description of the Type value
• Blocking: The Blocking attribute given in the .in file
• BlockingDesc: A textual description of the Blocking value
• Mode: The Mode attribute given in the .in file
• ModeDesc: A textual description of the Mode value
• Timestamp: The timestamp of the last execution of the request
• Id: The unique identifier of the request
• Result: The common result of the request execution

  Result	Description
  -6	Request wasn't executed, blocking not allowed for this type of request
  -5	Request wasn't executed, mode not allowed for this type of request
  -4	Request wasn't executed, required parameter(s) missing
  -3	Request returned an error during execution and was deleted
  -2	Request returned an error during execution and was requeued
  -1	Request returned an error during execution and blocks other requests
  0	Request was executed and returned an undefined result
  1	Request was executed successfully and will stay in request queue
  2	Request was executed successfully and was deleted

• ResultDesc: A textual description of the Result value
• ExecuteDuration: The amount of time needed for the execution of the request in milliseconds

Some request types need additional attributes for execution. These attributes are defined in the .in file in request-specific sections. The generated .out file always contains a request-specific section with further information about the results of the execution of the request.