Timebox
A role specifies a collection of rights. A role object contains a field, timebox, that defines the hours and days of the week that a role is either enabled or disabled. Setting the timebox field in a role object defines when a role’s rights are in effect.
You can read and set a role’s timebox field using the
Role.ApplicableTimeHexString property. You can modify an existing timebox value
one day or one hour at a time using the Role.GetSshRights and
Role.SetApplicableHour methods.
To interpret a timebox value, or to set it directly, however, you must know the timebox value format. This appendix explains following formats:
Hex string
The timebox value is a 42-character (21-byte) hexadecimal value stored as a string. When the hex value is converted to a binary value, its 168 bits each map to a single hour within the week. If a bit is set to 1, its corresponding hour is enabled for the role. If set to 0, its corresponding hour is disabled.
Hour mapping
Each day of the week takes three bytes (24 bits) to specify how its hours are enabled or disabled. The following tables show how the hours of a day are mapped to the bits within each of a day’s three bytes.
For byte 0 of each day of the week, you can enable or disable the hours a role is available from midnight to 8:00 AM:
| Hour | Bit |
|---|---|
| 12-1 AM | 0 (least-significant bit) |
| 1-2 AM | 1 |
| 2-3 AM | 2 |
| 3-4 AM | 3 |
| 4-5 AM | 4 |
| 5-6 AM | 5 |
| 6-7 AM | 6 |
| 7-8 AM | 7 (most-significant bit) |
For byte 1 of each day of the week, you can enable or disable the hours a role is available from 8:00 AM to 4:00 PM:
| Hour | Bit |
|---|---|
| 8-9 AM | 0 (least-significant bit) |
| 9-10 AM | 1 |
| 10-11 AM | 2 |
| 11-12 AM | 3 |
| 12-1 PM | 4 |
| 1-2 PM | 5 |
| 2-3 PM | 6 |
| 3-4 PM | 7 (most-significant bit) |
For byte 2 of each day of the week, you can enable or disable the hours a role is available from 4:00 PM to midnight:
| Hour | Bit |
|---|---|
| 4-5 PM | 0 (least-significant bit) |
| 5-6 PM | 1 |
| 6-7 PM | 2 |
| 7-8 PM | 3 |
| 8-9 PM | 4 |
| 9-10 PM | 5 |
| 10-11 PM | 6 |
| 11-12 PM | 7 (most-significant bit) |
Day mapping
Each of the seven days in a week have three bytes within the 21-byte timebox value. These bytes are in chronological order from most-significant byte to least-significant byte. (Note that this is the opposite of chronological bit order within each byte, which is LSB to MSB.)
The starting point of a week is 4 PM on Saturday afternoon.
The table below shows how each day’s three bytes (0-2) map to the timebox value’s bytes, listed here in order from most-significant byte to least-significant byte.
| Day byte | Timebox value byte |
|---|---|
| Saturday, byte 2 | 20 (most-significant byte) |
| Sunday, byte 0 | 19 |
| Sunday, byte 1 | 18 |
| Sunday, byte 2 | 17 |
| Monday, byte 0 | 16 |
| Monday, byte 1 | 15 |
| Monday, byte 2 | 14 |
| Tuesday, byte 0 | 13 |
| Tuesday, byte 1 | 12 |
| Tuesday, byte 2 | 11 |
| Wednesday, byte 0 | 10 |
| Wednesday, byte 1 | 9 |
| Wednesday, byte 2 | 8 |
| Thursday, byte 0 | 7 |
| Thursday, byte 1 | 6 |
| Thursday, byte 2 | 5 |
| Friday, byte 0 | 4 |
| Friday, byte 1 | 3 |
| Friday, byte 2 | 2 |
| Saturday, byte 0 | 1 |
| Saturday, byte 1 | 0 (least-significant byte) |