traits/hail.proto

Table of Contents

• traits/hail.proto

  • CreateHailRequest

  • DeleteHailRequest

  • DeleteHailResponse

  • GetHailRequest

  • Hail

  • Hail.Location

  • ListHailsRequest

  • ListHailsResponse

  • PullHailRequest

  • PullHailResponse

  • PullHailResponse.Change

  • PullHailsRequest

  • PullHailsResponse

  • PullHailsResponse.Change

  • UpdateHailRequest

  • Hail.State

  • HailApi

  • HailInfo

• Scalar Value Types

Top

traits/hail.proto

CreateHailRequest

Field	Type	Label	Description
name	string		The name of the device
hail	Hail

DeleteHailRequest

Field	Type	Label	Description
name	string		The name of the device
id	string		The id of the hail
allow_missing	bool		If true, no error is returned if a hail with the given id can't be found.

DeleteHailResponse

GetHailRequest

Field	Type	Label	Description
name	string		The name of the device
id	string		The id of the hail
read_mask	google.protobuf.FieldMask

Hail

A hail is a request from a caller to bring transport to the callers location. Like hailing a taxi.

Field	Type	Label	Description
id	string		A tracking id for this hail. This id may be used to subscribe or update the hail after creation.
origin	Hail.Location		The location for the start of the transportation. Optional. Supplied by the caller on write to indicate where the transport should "pick them up from", if absent on write the device typically has a defined location - i.e. a call button for a lift inherently has a floor associated.

During create the device is free to return a different origin location but that location should be a more specific variation to the supplied origin. For example you may create a hail with origin "Ground Floor" and the device returns a new, more specific origin of "Ground Floor, Lobby B, Door 3".

The origin should not change after the initial creation of the hail unless unavoidable. A changing origin can confuse callers who are not watching for hail changes. | | destination | Hail.Location | | The intended destination of the caller. Optional. Supplied by the caller on write, this indicates where the caller wishes to go. The device may return a more specific location as a response to creating a hail. | | state | Hail.State | | State reports which phase of the journey the transport is in. Output only.

Timestamps tracking the different states may report either the time the hail transitioned into that state or predict when the hail is expected to transition into that state. Compare state with the supplied times to know if it is a prediction or not. For example if state is CALLED and board_time is present, it represents a predicted boarding time; if state is DEPARTED, then board_time is the time the transport entered into the BOARDING state. | | call_time | google.protobuf.Timestamp | | The time the vehicle accepted the hail. | | board_time | google.protobuf.Timestamp | | The time the transport either began boarding or is expected to be boarding. | | depart_time | google.protobuf.Timestamp | | The time the transport either departed or is expected to be departing. | | arrive_time | google.protobuf.Timestamp | | The time the transport either arrived or is expected to arrive. |

Hail.Location

A logical location, typically in terms the hail creator will understand. Locations do not need to accurately or uniquely represent a physical space, instead they should unambiguously describe that location within the context of the device. For example "Floor 3" vs "lat:112.33,long:0.222,el:43.2", "Teal Room" vs "Teal Room, Floor 1, HQ, Birmingham, UK"

Field	Type	Label	Description
name	string		An unambiguous name for this location. Optional on write, if other location fields are used to identify the location. Required on output.
display_name	string		An unambiguous display name for the location. Will be presented to the client and should be recognised by people consuming this information.

ListHailsRequest

Field	Type	Label	Description
name	string		The name of the device.
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Hail type
page_size	int32		The maximum number of hails to return. The service may return fewer than this value. If unspecified, at most 50 items will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.
page_token	string		A page token, received from a previous ListHailsResponse call. Provide this to retrieve the subsequent page.

ListHailsResponse

Field	Type	Label	Description
hails	Hail	repeated
next_page_token	string		A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
total_size	int32		If non-zero this is the total number of hails. This may be an estimate.

PullHailRequest

Field	Type	Label	Description
name	string		The name of the device.
id	string		The id of the hail
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Hail type.
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

PullHailResponse

Field	Type	Label	Description
changes	PullHailResponse.Change	repeated

PullHailResponse.Change

Field	Type	Label	Description
name	string		Name of the device that issued the change.
change_time	google.protobuf.Timestamp		When the change occurred
hail	Hail		The new value for the hail.

PullHailsRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Hail type
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

PullHailsResponse

Field	Type	Label	Description
changes	PullHailsResponse.Change	repeated	The list of changes which have occurred

PullHailsResponse.Change

Field	Type	Label	Description
name	string		The name of the device that emitted this change
type	smartcore.types.ChangeType		The type of change (e.g. ADD, UPDATE, etc...)
new_value	Hail		The new value to use for ADD
old_value	Hail		The old value to use for UPDATE
change_time	google.protobuf.Timestamp		When the change occurred

UpdateHailRequest

Field	Type	Label	Description
name	string		The name of the device
hail	Hail		New hail properties. Id must be set.
update_mask	google.protobuf.FieldMask		A list of fields to update relative to the Hail type.

Hail.State

Name	Number	Description
STATE_UNSPECIFIED	0	The state has not been supplied.
CALLED	1	The hail has been accepted and the transport is on its way to the origin. Typically transitions into the BOARDING state.
BOARDING	2	The transport has arrived at the origin and is accepting passengers. Typically transitions into the DEPARTED state.
DEPARTED	3	The transport is moving to the destination. Typically transitions into the ARRIVED state.
ARRIVED	4	The transport is at the destination. This concludes this hail. The device may remove this hail once it has arrived. It is recommended that the device keep arrived hails for a short period of time (minutes) to aid clients who are checking or polling hail states to check for arrival. It is good practice, but not required, for a client to delete a hail once the information is no longer needed.

HailApi

HailApi describes devices that may be asked to transport passengers from one location to another. To interact with these devices you create a hail, a description of the origin and destination for your journey. The device keeps you updated on the preparation or progress of your journey by updating the fields in Hail.

HailApi applies to devices like lifts or taxis, where the transportation is initiated by the caller. It does not apply to scheduled/regular transportation - like busses or escalators - where the presence of the passenger is not required.

Method Name	Request Type	Response Type	Description
CreateHail	CreateHailRequest	Hail	Create a new hail against the device. Creating a hail instructs the device that a passenger would like to be transported from one location to another. The response from this request may include additional location information than that supplied. See Hail.origin for more details.

If Hail.id is specified and is used by an existing hail the device will return an error. If Hail.id is specified the device may return an error indicating that client supplied ids are not supported. | | GetHail | GetHailRequest | Hail | Retrieve details on a specific hail by id as returned by CreateHail. | | UpdateHail | UpdateHailRequest | Hail | Update a hail by id. Hail.id must be present. | | DeleteHail | DeleteHailRequest | DeleteHailResponse | Delete a hail by id. | | PullHail | PullHailRequest | PullHailResponse stream | Subscribe to changes in a specific hail. | | ListHails | ListHailsRequest | ListHailsResponse | List known hails. | | PullHails | PullHailsRequest | PullHailsResponse stream | Subscribe to changes in the known hails. |

HailInfo

todo: define HailInfo, including listing available locations.

Method Name	Request Type	Response Type	Description

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)