Worked on jump list script and documentation

libyal · Mar 10, 2024 · 7a6c4bc · 7a6c4bc
1 parent 7119ebf
commit 7a6c4bc
Show file tree

Hide file tree

Showing 7 changed files with 2,532 additions and 262 deletions.
diff --git a/documentation/Jump lists format.asciidoc b/documentation/Jump lists format.asciidoc
@@ -29,7 +29,7 @@ specification.
 == License
 
 ....
-Copyright (C) 2014-2023, Joachim Metz <[email protected]>.
+Copyright (C) 2014-2024, Joachim Metz <[email protected]>.
 Permission is granted to copy, distribute and/or modify this document under the
 terms of the GNU Free Documentation License, Version 1.3 or any later version
 published by the Free Software Foundation; with no Invariant Sections, no
@@ -50,6 +50,7 @@ in the section entitled "GNU Free Documentation License".
 | 0.0.5 | J.B. Metz | March 2016 | Additional information about format version 4 automatic destinations jump lists with thanks to E. Zimmerman.
 | 0.0.6 | J.B. Metz | June 2019 | Corrected typos and formatting changes.
 | 0.0.7 | J.B. Metz | February 2023 | Additional information about format version 2.
+| 0.0.8 | J.B. Metz | March 2024 | Additional information about custom destinations jump lists.
 |===
 
 :numbered:
@@ -60,6 +61,7 @@ introduced in Windows 7, that gives the user quick access to recently accessed
 application files and actions.
 
 The automatic and custom destinations Jump lists are stored in:
+
 ....
 C:\Users\%USERNAME%\AppData\Roaming\Microsoft\Windows\Recent\
 ....
@@ -69,18 +71,18 @@ This directory contains Windows Shortcut (LNK) files and the following sub direc
 * AutomaticDestinations
 * CustomDestinations
 
-For more information about the LNK format see: https://github.com/libyal/liblnk/blob/master/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
+For more information about the LNK format see: https://github.com/libyal/liblnk/blob/main/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
 
 Additionally Jump lists can be stored in:
 
-* Explorer ProgramsCache Registry values see: https://github.com/libyal/winreg-kb/blob/master/documentation/Programs%20Cache%20values.asciidoc[[WINREG-KB\]].
+* Explorer ProgramsCache Registry values see: https://winreg-kb.readthedocs.io/en/latest/sources/explorer-keys/Program-cache.html[[WINREG-KB\]].
 
 == Automatic destinations files
 
 The automatic destinations files are stored in the AutomaticDestinations sub
 directory and have the extension .automaticDestinations-ms. The automatic
 destinations file uses the Object Linking and Embedding (OLE) Compound File
-(CF) format. For more information about the OLECF format see: https://github.com/libyal/libolecf/blob/master/documentation/OLE%20Compound%20File%20format.asciidoc[[LIBOLECF\]].
+(CF) format. For more information about the OLECF format see: https://github.com/libyal/libolecf/blob/main/documentation/OLE%20Compound%20File%20format.asciidoc[[LIBOLECF\]].
 
 The automatic destinations OLECF file contains the following streams:
 
@@ -131,7 +133,7 @@ See section: <<destlist_format_versions,Format versions>>
 
 ===== DestList entry - version 1
 
-The DestList entry - version 1 is variable of size and consists of:
+The DestList entry - version 1 is of variable size and consists of:
 
 [cols="1,1,1,5",options="header"]
 |===
@@ -172,7 +174,7 @@ The path can point to:
 
 ===== DestList entry - version 2 or later
 
-The DestList entry - version 2 or later is variable of size and consists of:
+The DestList entry - version 2 or later is of variable size and consists of:
 
 [cols="1,1,1,5",options="header"]
 |===
@@ -215,7 +217,7 @@ such as "U+d800" and "U+dc00".
 === Hexadecimal numbered streams
 
 A hexadecimal numbered streams contains a Windows Shortcut (LNK) file. For more
-information about the LNK format see: https://github.com/libyal/liblnk/blob/master/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
+information about the LNK format see: https://github.com/libyal/liblnk/blob/main/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
 
 == Custom destinations files
 
@@ -225,118 +227,79 @@ directory and have the extension .customDestinations-ms.
 The custom destinations file consists of:
 
 * File header
-* An array Windows Shortcut (LNK) file entries
-* File footer
-* [yellow-background]*Trailing data?*
+* One or more categories
 
 === File header
 
-The custom destinations file header is variable of size and consists of:
+The custom destinations file header is of variable size and consists of:
 
 [cols="1,1,1,5",options="header"]
 |===
 | Offset | Size | Value | Description
-| 0 | 4 | 2 | [yellow-background]*Unknown (format version?)*
-| 4 | 4 | | [yellow-background]*Unknown (Number of header values?)* +
-[yellow-background]*Seen: 1, 2*
+| 0 | 4 | 2 | Format version
+| 4 | 4 | | Number of categories
 | 8 | 4 | | [yellow-background]*Unknown (empty values)*
-| 12 | 4 | | [yellow-background]*Unknown (Header values type?)*
-4+| _If header values type == 0_
-| 16 | 2 | | String number of characters
-| 18 | ... | | String +
+|===
+
+=== Category
+
+A custom destinations category is of variable size and consists of:
+
+|===
+| 0 | 4 | | Category type +
+See section: <<category_types,Category types>>
+4+| _If category type == 0_
+| 4 | 2 | | String number of characters
+| 6 | ... | | Title string +
 Contains an UTF-16 little-endian string without an end-of-string character
 4+| _Common_
 | ... | 4 | | Number of entries
+| ... | ... | | Entries +
+Contains an array shell object entries
+| ... | 4 | 0xbabffbab | Footer signature
 |===
 
-=== [yellow-background]*Header values types?*
+[NOTE]
+The number of entries is not reliable.
+
+==== [[category_types]]Category types
 
 [cols="1,1,5",options="header"]
 |===
 | Value | Identifier | Description
-| 0x00000000 | | [yellow-background]*Unknown (String?)*
-| 0x00000001 | | [yellow-background]*Unknown*
-| 0x00000002 | | [yellow-background]*Unknown*
+| 0 | | Custom destinations
+| 1 | | Known destinations
+| 2 | | Custom tasks
 |===
 
-....
-00000000  02 00 00 00 02 00 00 00  00 00 00 00 00 00 00 00  |................|
-00000010  0c 00 4d 00 6f 00 73 00  74 00 20 00 76 00 69 00  |..M.o.s.t. .v.i.|
-00000020  73 00 69 00 74 00 65 00  64 00 05 00 00 00 01 14  |s.i.t.e.d.......|
-00000030  02 00 00 00 00 00 c0 00  00 00 00 00 00 46        |.............FL.|
-
-00000030                                             4c 00  |.............FL.|
-00000040  00 00 01 14 02 00 00 00  00 00 c0 00 00 00 00 00  |................|
-00000050  00 46 a3 00 20 00 20 20  00 00 4a 30 d8 5c 56 5b  |.F.. .  ..J0.\V[|
-00000060  cc 01 15 01 53 e0 f6 13  cd 01 3d 0c cd 2e 06 12  |....S.....=.....|
-00000070  cd 01 f0 ad 12 00 00 00  00 00 01 00 00 00 00 00  |................|
-00000080  00 00 00 00 00 00 00 00  00 00 38 02 14 00 1f 44  |..........8....D|
-00000090  47 1a 03 59 72 3f a7 44  89 c5 55 95 fe 6b 30 ee  |G..Yr?.D..U..k0.|
-....
+==== Shell object entry
 
-Empty
-....
-00000000  02 00 00 00 01 00 00 00  00 00 00 00 01 00 00 00  |................|
-00000010  01 00 00 00 ab fb bf ba                           |........|
-
-00000000  02 00 00 00 01 00 00 00  00 00 00 00 02 00 00 00  |................|
-00000010  09 00 00 00 01 14 02 00  00 00 00 00 c0 00 00 00  |................|
-00000020  00 00 00 46                                       |...FL...........|
-
-00000020              4c 00 00 00  01 14 02 00 00 00 00 00  |...FL...........|
-00000030  c0 00 00 00 00 00 00 46  e7 02 20 00 20 00 00 00  |.......F.. . ...|
-00000040  8b 29 81 76 15 04 ca 01  8b 29 81 76 15 04 ca 01  |.).v.....).v....|
-....
-
-[yellow-background]*TODO*
-
-=== Windows Shortcut (LNK) file entry
-
-The Windows Shortcut (LNK) file entry is variable of size and consists of:
+The shell object entry is of variable size and consists of:
 
 [cols="1,1,1,5",options="header"]
 |===
 | Offset | Size | Value | Description
 | 0 | 16 | | Class identifier +
-Contains a GUID +
-00021401-0000-0000-c000-000000000046 (Windows Shortcut (LNK))
-| 16 | ... | | Data stream +
-Contains a Windows Shortcut (LNK) file. For more information about the LNK format see: https://github.com/libyal/liblnk/blob/master/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
+Contains a GUID
+| 16 | ... | | Shell object data
 |===
 
-[NOTE]
-The file size in the Windows Shortcut (LNK) file data stream is not reliable
-for indicating the size of the data stream (file).
+===== Windows Shortcut (LNK) file entry
 
-=== File footer
-
-The custom destinations file footer is 4 bytes of size and consists of:
+The Windows Shortcut (LNK) file entry is of variable size and consists of:
 
 [cols="1,1,1,5",options="header"]
 |===
 | Offset | Size | Value | Description
-| 0 | 4 | 0xbabffbab | Signature
+| 0 | 16 | 00021401-0000-0000-c000-000000000046 | Windows Shortcut (LNK) class identifier +
+Contains a GUID
+| 16 | ... | | Windows Shortcut (LNK) file shell object data +
+For more information about the LNK format see: https://github.com/libyal/liblnk/blob/main/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
 |===
 
-=== Notes
-
-[yellow-background]*Trailing data?*
-
-[cols="1,1,1,5",options="header"]
-|===
-| ... | 4 | 0xbabffbab | Signature
-| ... | 4 | | [yellow-background]*Unknown (empty values)*
-| ... | 2 | | Number of characters
-| 114 | ... | | string +
-Contains a UTF-16 little-endian string without an end-of-string character
-| ... | 4 | | [yellow-background]*Unknown*
-| ... | 16 | | Class identifier +
-Contains a GUID +
-00021401-0000-0000-c000-000000000046 (Windows Shortcut (LNK))
-| ... | ... | | Data stream +
-Contains a Windows Shortcut (LNK) file. For more information about the LNK format see: https://github.com/libyal/liblnk/blob/master/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc[[LIBLNK\]].
-| ... | ... | | 0xbabffbab | Footer signature
-|===
+[NOTE]
+The file size in the Windows Shortcut (LNK) file is not reliable for indicating
+the size of the shell object data.
 
 == Notes
 
@@ -379,6 +342,7 @@ Contains a Windows Shortcut (LNK) file. For more information about the LNK forma
 http://www.hexacorn.com/blog/2013/04/30/jumplists-file-names-and-appid-calculator/
 
 Where the filename starts with the identifier of the corresponding application e.g.
+
 ....
 %ID%.customDestinations-ms
 ....
@@ -400,7 +364,7 @@ Where %ID% a 64-bit CRC of full path of executable file of the corresponding app
 | Title: | Windows Shortcut File format specification
 | Author(s): | Joachim Metz
 | Date: | September 2009
-| URL: | https://github.com/libyal/liblnk/blob/master/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc
+| URL: | https://github.com/libyal/liblnk/blob/main/documentation/Windows%20Shortcut%20File%20(LNK)%20format.asciidoc
 |===
 
 `[LIBOLECF]`
@@ -410,7 +374,7 @@ Where %ID% a 64-bit CRC of full path of executable file of the corresponding app
 | Title: | Object Linking and Embedding (OLE) Compound File (CF) format specification
 | Author(s): | Joachim Metz
 | Date: | December 2008
-| URL: | https://github.com/libyal/libolecf/blob/master/documentation/OLE%20Compound%20File%20format.asciidoc
+| URL: | https://github.com/libyal/libolecf/blob/main/documentation/OLE%20Compound%20File%20format.asciidoc
 |===
 
 `[WINREG-KB]`
@@ -420,7 +384,7 @@ Where %ID% a 64-bit CRC of full path of executable file of the corresponding app
 | Title: | Explorer ProgramsCache Registry values
 | Author(s): | Joachim Metz
 | Date: | June 2013
-| URL: | https://github.com/libyal/winreg-kb/blob/master/documentation/Programs%20Cache%20values.asciidoc
+| URL: | https://winreg-kb.readthedocs.io/en/latest/sources/explorer-keys/Program-cache.html
 |===
 
 [appendix]

diff --git a/dtformats/jump_list.debug.yaml b/dtformats/jump_list.debug.yaml
@@ -1,25 +1,37 @@
 # dtFormats debug specification.
 ---
-data_type_map: custom_file_footer
+data_type_map: custom_category_footer
 attributes:
 - name: signature
   description: "Signature"
-  format: hexadecimal_8digits
+  format: binary_data
+---
+data_type_map: custom_category_header
+attributes:
+- name: category_type
+  description: "Category type"
+  format: custom:category_type
+- name: number_of_characters
+  description: "Number of characters"
+  format: decimal
+- name: title
+  description: "Title"
+  format: string
+- name: number_of_entries
+  description: "Number of entries"
+  format: decimal
 ---
 data_type_map: custom_file_header
 attributes:
+- name: format_version
+  description: "Format version"
+  format: decimal
+- name: number_of_categories
+  description: "Number of categories"
+  format: decimal
 - name: unknown1
   description: "Unknown1"
   format: hexadecimal_8digits
-- name: unknown2
-  description: "Unknown2"
-  format: hexadecimal_8digits
-- name: unknown3
-  description: "Unknown3"
-  format: hexadecimal_8digits
-- name: header_values_type
-  description: "Header value type"
-  format: decimal
 ---
 data_type_map: dest_list_entry
 attributes: