Package org.opencabstandard.provider

Class HOSContract

java.lang.Object

org.opencabstandard.provider.HOSContract

public final class HOSContract
extends Object

HOS Contract Provider

Defines the contract for the OpenCab HOS Content provider. An OpenCab HOS provider app should define an Android ContentProvider class that follows this contract or should extend the AbstractHOSProvider class and implement the abstract methods.

Displaying duty status and hours of service for a single driver

sequenceDiagram participant A as HOS Consumer participant B as HOS Provider Note over A: App enumerates available HOS providers and selects HOS Provider app. Note over A: App queries HOS provider for current HOS status. A->>B: Call HOSContract.METHOD_GET_HOS("0.3") Note over B: App returns current HOS status for the primary driver using
the existing KEY_HOS mechanism. Because the provider app
supports OpenCab-based team driving, it includes an empty
KEY_TEAM_HOS value, indicating there are no additional
team drivers. B->>A: Return
Bundle{
KEY_VERSION="0.3"
KEY_HOS=HOSStatus{
manageAction="example://com.example.hosprovider/manage"
logoutAction="example://com.example.hosprovider/inspect"
clocks=[
Clock{label="Driver 1", valueType=STRING, value="A"},
Clock{label="Status", valueType=STRING, value="D"},
Clock{label="Driving left", valueType=STRING,
value="8:00", durationSeconds=28800},
Clock{label="Rest in", valueType=STRING,
value="0:23", durationSeconds=1380, limitsDrivingRange=true}
]}
KEY_TEAM_HOS=null
} Note over A: App displays Driver A's clocks.

Displaying duty status and hours of service for two drivers

sequenceDiagram participant A as HOS Consumer participant B as HOS Provider Note over A: App queries HOS provider for current HOS status. A->>B: Call HOSContract.METHOD_GET_HOS("0.3") Note over B: App returns current HOS status for the primary driver using
the existing KEY_HOS mechanism, and clocks for the
additional driver (driver B) in the KEY_TEAM_HOS array. B->>A: Return
Bundle{
KEY_VERSION="0.3"
KEY_HOS=HOSStatus{
manageAction="example://com.example.hosprovider/manage"
logoutAction="example://com.example.hosprovider/inspect"
clocks=[
Clock{label="Driver 1", valueType=STRING, value="A"},
Clock{label="Status", valueType=STRING, value="D"},
Clock{label="Driving left", valueType=STRING,
value="8:00", durationSeconds=28800},
Clock{label="Rest in", valueType=STRING,
value="0:23", durationSeconds=1380, limitsDrivingRange=true}
]}
KEY_TEAM_HOS=[HOSStatus{
clocks=[
Clock{label="Driver 2", valueType=STRING, value="A"},
Clock{label="Status", valueType=STRING, value="SB"},
Clock{label="Rest in", valueType=STRING, value="0:00", durationSeconds=0}
]}]
} Note over A: The app displays duty status and clocks for both driver A
and driver B based on the returned information. Normally,
the consuming app SHOULD display both sets of clocks
with the clocks from KEY_HOS displayed first.

Since KEY_TEAM_HOS is an array, a third or fourth driver's clocks could also be returned and displayed.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	HOSContract.Clock	Object representing an HOS clock for version 0.2.
static class	HOSContract.ClockData	Object representing an HOS clock for version 0.4.
static class	HOSContract.ClockV2	Object representing an HOS clock for version 0.3.
static class	HOSContract.HOSData	An object representing the HOS data for version 0.4
static class	HOSContract.HOSStatus	An object representing the HOS status for version 0.2.
static class	HOSContract.HOSStatusV2	An object representing the HOS status for version 0.3.
static class	HOSContract.HOSTeamData	An object representing the HOS Team Data for version 0.4.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	AUTHORITY	This authority is used for querying the HOS provider.
static final String	KEY_ERROR	If an error has occurred in one of the provider method calls, use this key to retrieve the error from the Bundle object returned from the provider call method.
static final String	KEY_HOS	Key for retrieving the HOS status from the returned Bundle object.
static final String	KEY_NAVIGATION_RESULT	For the methods HOSContract.METHOD_START_NAVIGATION and HOSContract.METHOD_END_NAVIGATION, the returned Bundle object will contain this key which maps to a Boolean indicating success or failure.
static final String	KEY_TEAM_HOS	Key for retrieving the HOS status from the returned Bundle object.
static final String	KEY_VERSION	For the methods HOSContract.METHOD_GET_HOS, the returned Bundle object will contain this key which maps to String indicating HOS Clocks version supported.
static final String	METHOD_END_NAVIGATION	Provider method name indicating that the OpenCab consumer app has ended navigation.
static final String	METHOD_GET_HOS	Provider method name for retrieving the current HOS.
static final String	METHOD_START_NAVIGATION	Provider method name indicating that the OpenCab consumer app has started navigation.
static final String	VERSION	This is the current version of the HOSContract for the OpenCab Standard.

Constructor Summary

Constructors

Constructor	Description
HOSContract()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

VERSION

public static final String VERSION

This is the current version of the HOSContract for the OpenCab Standard. The version will be passed as an argument to all method calls to the provider. The provider may reject or handle appropriately if the VERSION does not match the expected value when passed to the method calls.

See Also:

• Constant Field Values

AUTHORITY

public static final String AUTHORITY

This authority is used for querying the HOS provider. This should be declared in the manifest as the authority for the HOS provider.

See Also:

• Constant Field Values

METHOD_GET_HOS

public static final String METHOD_GET_HOS

Provider method name for retrieving the current HOS. The returned object contains a list of clocks. The clocks can be displayed in the OpenCab HOS consumer app to provide the driver update to date information about his current HOS status. This method can take some time to execute, so the consumer app should avoid making this call on the main thread as it could cause the app to become unresponsive.

Example:

 

     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_GET_HOS,
                                  HOSContract.VERSION,
                                  null);
     HOSContract.HOSStatus status = result.getParcelableArrayList(HOSContract.KEY_HOS);
 
 

Diagram:

sequenceDiagram participant A as OpenCab Consumer participant B as OpenCab Provider A->>B: contentResolver.call(Uri.parse("content://org.opencabstandard.hos"), "getHOS", "0.3", null) B->>A: android.os.Bundle

See Also:

• Constant Field Values

METHOD_START_NAVIGATION

public static final String METHOD_START_NAVIGATION

Provider method name indicating that the OpenCab consumer app has started navigation. The OpenCab provider app can use this as an indicator that it is not necessary to lock the screen due to vehicle motion.

Example:

 
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_START_NAVIGATION,
                                  HOSContract.VERSION,
                                  null);
     Boolean status = result.getBoolean(HOSContract.KEY_NAVIGATION_RESULT);
 
 

Diagram:

sequenceDiagram participant A as OpenCab Consumer participant B as OpenCab Provider A->>B: contentResolver.call(Uri.parse("content://org.opencabstandard.hos"), "startNavigation", "0.2", null) B->>A: android.os.Bundle

See Also:

• Constant Field Values

METHOD_END_NAVIGATION

public static final String METHOD_END_NAVIGATION

Provider method name indicating that the OpenCab consumer app has ended navigation. The OpenCab provider app can use this as an indicator that it can lock the screen due to vehicle motion.

Example:

 
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_END_NAVIGATION,
                                  HOSContract.VERSION,
                                  null);
     Boolean status = result.getBoolean(HOSContract.KEY_NAVIGATION_RESULT);
 
 

Diagram:

sequenceDiagram participant A as OpenCab Consumer participant B as OpenCab Provider A->>B: contentResolver.call(Uri.parse("content://org.opencabstandard.hos"), "endNavigation", "0.2", null) B->>A: android.os.Bundle

See Also:

• Constant Field Values

KEY_HOS

public static final String KEY_HOS

Key for retrieving the HOS status from the returned Bundle object. If the value is null, an error occurred and you can then retrieve the error from the Bundle using the key HOSContract.KEY_ERROR.

Example:

 
      ContentResolver resolver = getApplicationContext().getContentResolver();
      Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_GET_HOS,
                                  HOSContract.VERSION,
                                  null);
     HOSContract.HOSStatusV2 status = result.getParelable(HOSContract.KEY_HOS);
 
 

See Also:

• Constant Field Values

KEY_TEAM_HOS

public static final String KEY_TEAM_HOS

Key for retrieving the HOS status from the returned Bundle object. If the value is null, an error occurred and you can then retrieve the error from the Bundle using the key HOSContract.KEY_ERROR.

This property will contain an array of HOSContract.HOSStatusV2 parceled objects, each representing the HOS status and clocks for a different driver.

Example:

 
      ContentResolver resolver = getApplicationContext().getContentResolver();
      Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_GET_HOS,
                                  HOSContract.VERSION,
                                  null);
     ArrayList<HOSContract.HOSStatusV2> status = result.getParcelableArrayList(HOSContract.KEY_TEAM_HOS);
 
 

See Also:

• Constant Field Values

KEY_ERROR

public static final String KEY_ERROR

If an error has occurred in one of the provider method calls, use this key to retrieve the error from the Bundle object returned from the provider call method.

Example:

 
     Bundle result = provider.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  "ANY METHOD",
                                  HOSContract.VERSION,
                                  null);
     String error = result.getString(HOSContract.KEY_ERROR);
 
 

See Also:

• Constant Field Values

KEY_NAVIGATION_RESULT

public static final String KEY_NAVIGATION_RESULT

For the methods HOSContract.METHOD_START_NAVIGATION and HOSContract.METHOD_END_NAVIGATION, the returned Bundle object will contain this key which maps to a Boolean indicating success or failure.

Example:

 
     Bundle result = provider.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_START_NAVIGATION,
                                  HOSContract.VERSION,
                                  null);
     Boolean status = result.getBoolean(HOSContract.KEY_NAVIGATION_RESULT);
 
 

See Also:

• Constant Field Values

KEY_VERSION

public static final String KEY_VERSION

For the methods HOSContract.METHOD_GET_HOS, the returned Bundle object will contain this key which maps to String indicating HOS Clocks version supported.

Example:

 
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  HOSContract.METHOD_GET_HOS,
                                  HOSContract.VERSION,
                                  null);
     String version = result.getBoolean(HOSContract.KEY_VERSION);
 
 

See Also:

• Constant Field Values

Constructor Details

HOSContract

public HOSContract()