Timebox Value Format
A Delinearole specifies a collection of rights. A role object contains a field, timebox, that defines what hours in a week 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 a role’s timebox field using the ADEdit command get_role_field and set the timebox value using set_role_field. You can modify an existing timebox value one hour at a time using the ADEdit library command modify_timebox.
To interpret a timebox value, or to set it directly, you must know the timebox value format which is, unfortunately, not simple as defined by Active Directory. This appendix explains the format.
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.
After you define the 168 bits using a hexadecimal value, you can usee the encode_timebox function to convert the value into an internal format that specifies when a role is available to use.
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.
Byte 0
| 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) |
Byte 1
| 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) |
Byte 2
| 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) |
