dll/win32/shell32/pidl.h

   1 /*
   2  * internal pidl functions
   3  *
   4  * Copyright 1998 Juergen Schmied
   5  * Copyright 2004 Juan Lang
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  20  *
  21  * NOTES:
  22  *
  23  * DO NOT use this definitions outside the shell32.dll !
  24  *
  25  * The contents of a pidl should never used from a application
  26  * directly.
  27  *
  28  * Undocumented:
  29  * MS says: the abID of SHITEMID should be treated as binary data and not
  30  * be interpreted by applications. Applies to everyone but MS itself.
  31  * Word95 interprets the contents of abID (Filesize/Date) so we have to go
  32  * for binary compatibility here.
  33  */
  34
  35 #ifndef __WINE_PIDL_H
  36 #define __WINE_PIDL_H
  37
  38 /*
  39 * the pidl does cache fileattributes to speed up SHGetAttributes when
  40 * displaying a big number of files.
  41 *
  42 * a pidl of NULL means the desktop
  43 *
  44 * The structure of the pidl seems to be a union. The first byte of the
  45 * PIDLDATA describes the type of pidl.
  46 *
  47 *   object        ! first byte /  ! format       ! living space
  48 *                 ! size
  49 *   ----------------------------------------------------------------
  50 *   my computer 0x1F/20     guid (2)    (usual)
  51 *   network     0x1F        guid
  52 *   bitbucket   0x1F        guid
  53 *   drive       0x23/25     drive       (usual)
  54 *   drive       0x25/25     drive       (lnk/persistent)
  55 *   drive       0x29/25     drive
  56 *   shell extension 0x2E        guid
  57 *   drive       0x2F        drive       (lnk/persistent)
  58 *   folder/file 0x30        folder/file (1) (lnk/persistent)
  59 *   folder      0x31        folder      (usual)
  60 *   valueA      0x32        file        (ANSI file name)
  61 *   valueW      0x34        file        (Unicode file name)
  62 *   workgroup   0x41        network (3)
  63 *   computer    0x42        network (4)
  64 *   net provider    0x46        network
  65 *   whole network   0x47        network (5)
  66 *   MSITStore   0x61        htmlhlp (7)
  67 *   printers/ras connections    0x70        guid
  68 *   history/favorites 0xb1      file
  69 *   share       0xc3        network (6)
  70 *
  71 * guess: the persistent elements are non tracking
  72 *
  73 * (1) dummy byte is used, attributes are empty
  74 * (2) IID_MyComputer = 20D04FE0L-3AEA-1069-A2D8-08002B30309D
  75 * (3) two strings   "workgroup" "Microsoft Network"
  76 * (4) two strings   "\\sirius" "Microsoft Network"
  77 * (5) one string    "Entire Network"
  78 * (6) two strings   "\\sirius\c" "Microsoft Network"
  79 * (7) contains string   "mk:@MSITStore:C:\path\file.chm::/path/filename.htm"
  80 *       GUID    871C5380-42A0-1069-A2EA-08002B30309D
  81 */
  82
  83 #define PT_CPLAPPLET    0x00
  84 #define PT_GUID     0x1F
  85 #define PT_DRIVE    0x23
  86 #define PT_DRIVE2   0x25
  87 #define PT_DRIVE3   0x29
  88 #define PT_SHELLEXT 0x2E
  89 #define PT_DRIVE1   0x2F
  90 #define PT_FOLDER1  0x30
  91 #define PT_FOLDER   0x31
  92 #define PT_VALUE    0x32
  93 #define PT_VALUEW       0x34
  94 #define PT_WORKGRP  0x41
  95 #define PT_COMP     0x42
  96 #define PT_NETPROVIDER  0x46
  97 #define PT_NETWORK  0x47
  98 #define PT_IESPECIAL1   0x61
  99 #define PT_YAGUID   0x70 /* yet another guid.. */
 100 #define PT_CPEXT    0x71
 101 #define PT_IESPECIAL2   0xb1
 102 #define PT_SHARE    0xc3
 103
 104 #include "pshpack1.h"
 105 typedef BYTE PIDLTYPE;
 106
 107 typedef struct tagPIDLCPanelStruct
 108 {
 109     BYTE dummy;         /*01 is 0x00 */
 110     DWORD iconIdx;      /*02 negative icon ID */
 111     WORD offsDispName;      /*06*/
 112     WORD offsComment;       /*08*/
 113     CHAR szName[1];     /*10*/ /* terminated by 0x00, followed by display name and comment string */
 114 } PIDLCPanelStruct;
 115
 116 typedef struct tagPIDLFontStruct
 117 {
 118     BYTE dummy;
 119     WORD offsFile;
 120     WCHAR szName[1];
 121 } PIDLFontStruct;
 122
 123 typedef struct tagPIDLPrinterStruct
 124 {
 125     BYTE dummy;
 126     DWORD Attributes;
 127     WORD offsServer;
 128     WCHAR szName[1];
 129 } PIDLPrinterStruct;
 130
 131 typedef struct tagPIDLRecycleStruct
 132 {
 133     FILETIME LastModification;
 134     FILETIME DeletionTime;
 135     ULARGE_INTEGER FileSize;
 136     ULARGE_INTEGER PhysicalFileSize;
 137     DWORD Attributes;
 138     WCHAR szName[1];
 139 } PIDLRecycleStruct;
 140
 141 typedef struct tagGUIDStruct
 142 {
 143     BYTE dummy; /* offset 01 is unknown */
 144     GUID guid;  /* offset 02 */
 145 } GUIDStruct;
 146
 147 typedef struct tagDriveStruct
 148 {
 149     CHAR szDriveName[20];   /*01*/
 150     WORD unknown;       /*21*/
 151 } DriveStruct;
 152
 153 typedef struct tagFileStruct
 154 {
 155     BYTE dummy;         /*01 is 0x00 for files or dirs */
 156     DWORD dwFileSize;       /*02*/
 157     WORD uFileDate;     /*06*/
 158     WORD uFileTime;     /*08*/
 159     WORD uFileAttribs;      /*10*/
 160     CHAR szNames[1];        /*12*/
 161     /* Here are coming two strings. The first is the long name.
 162     The second the dos name when needed or just 0x00 */
 163 } FileStruct;
 164
 165 /* At least on WinXP, this struct is appended with 2-byte-alignment to FileStruct. There follows
 166  * a WORD member after the wszName string, which gives the offset from the beginning of the PIDL
 167  * to the FileStructW member. */
 168 typedef struct tagFileStructW {
 169     WORD cbLen;
 170     BYTE dummy1[6];
 171     WORD uCreationDate;
 172     WORD uCreationTime;
 173     WORD uLastAccessDate;
 174     WORD uLastAccessTime;
 175     BYTE dummy2[4];
 176     WCHAR wszName[1];
 177 } FileStructW;
 178
 179 typedef struct tagValueW
 180 {
 181     WCHAR name[1];
 182 } ValueWStruct;
 183
 184 typedef struct tagPIDLDATA
 185 {   PIDLTYPE type;          /*00*/
 186     union
 187     {
 188         struct tagGUIDStruct guid;
 189         struct tagDriveStruct drive;
 190         struct tagFileStruct file;
 191         struct
 192         {   WORD dummy;     /*01*/
 193             CHAR szNames[1];    /*03*/
 194         } network;
 195         struct
 196         {   WORD dummy;     /*01*/
 197             DWORD dummy1;   /*02*/
 198             CHAR szName[1]; /*06*/ /* terminated by 0x00 0x00 */
 199         } htmlhelp;
 200         struct tagPIDLCPanelStruct cpanel;
 201         struct tagValueW valueW;
 202         struct tagPIDLFontStruct cfont;
 203         struct tagPIDLPrinterStruct cprinter;
 204         struct tagPIDLRecycleStruct crecycle;
 205     } u;
 206 } PIDLDATA, *LPPIDLDATA;
 207 #include "poppack.h"
 208
 209 /*
 210  * getting special values from simple pidls
 211  */
 212 DWORD   _ILSimpleGetText    (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 213 DWORD   _ILSimpleGetTextW   (LPCITEMIDLIST pidl, LPWSTR pOut, UINT uOutSize);
 214 BOOL    _ILGetFileDate      (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 215 DWORD   _ILGetFileSize      (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 216 BOOL    _ILGetExtension     (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 217 void    _ILGetFileType      (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 218 DWORD   _ILGetFileAttributes    (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 219
 220 BOOL    _ILGetFileDateTime  (LPCITEMIDLIST pidl, FILETIME *ft);
 221 DWORD   _ILGetDrive     (LPCITEMIDLIST, LPSTR, UINT);
 222
 223 /*
 224  * testing simple pidls
 225  */
 226 BOOL    _ILIsUnicode        (LPCITEMIDLIST pidl);
 227 BOOL    _ILIsDesktop        (LPCITEMIDLIST pidl);
 228 BOOL    _ILIsMyComputer     (LPCITEMIDLIST pidl);
 229 BOOL    _ILIsPrinter        (LPCITEMIDLIST pidl);
 230 BOOL    _ILIsMyDocuments       (LPCITEMIDLIST pidl);
 231 BOOL    _ILIsControlPanel       (LPCITEMIDLIST pidl);
 232 BOOL    _ILIsBitBucket      (LPCITEMIDLIST pidl);
 233 BOOL    _ILIsAdminTools (LPCITEMIDLIST pidl);
 234 BOOL    _ILIsNetHood      (LPCITEMIDLIST pidl);
 235 BOOL    _ILIsDrive      (LPCITEMIDLIST pidl);
 236 BOOL    _ILIsFolder     (LPCITEMIDLIST pidl);
 237 BOOL    _ILIsValue      (LPCITEMIDLIST pidl);
 238 BOOL    _ILIsSpecialFolder  (LPCITEMIDLIST pidl);
 239 BOOL    _ILIsPidlSimple     (LPCITEMIDLIST pidl);
 240 BOOL    _ILIsCPanelStruct   (LPCITEMIDLIST pidl);
 241 static BOOL __inline _ILIsEqualSimple        (LPCITEMIDLIST pidlA, LPCITEMIDLIST pidlB)
 242 {
 243     return (pidlA->mkid.cb > 0 && !memcmp(pidlA, pidlB, pidlA->mkid.cb)) ||
 244            (!pidlA->mkid.cb && !pidlB->mkid.cb);
 245 }
 246 static
 247 BOOL  __inline _ILIsEmpty              (LPCITEMIDLIST pidl) {
 248     return _ILIsDesktop(pidl);
 249 }
 250
 251 /*
 252  * simple pidls
 253  */
 254
 255 /* Creates a PIDL with guid format and type type, which must be one of PT_GUID,
 256  * PT_SHELLEXT, or PT_YAGUID.
 257  */
 258 LPITEMIDLIST    _ILCreateGuid(PIDLTYPE type, REFIID guid);
 259
 260 /* Like _ILCreateGuid, but using the string szGUID. */
 261 LPITEMIDLIST    _ILCreateGuidFromStrA(LPCSTR szGUID);
 262 LPITEMIDLIST    _ILCreateGuidFromStrW(LPCWSTR szGUID);
 263
 264 /* Commonly used PIDLs representing file system objects. */
 265 LPITEMIDLIST    _ILCreateDesktop    (void);
 266 LPITEMIDLIST    _ILCreateFromFindDataW(const WIN32_FIND_DATAW *stffile);
 267 HRESULT     _ILCreateFromPathW  (LPCWSTR szPath, LPITEMIDLIST* ppidl);
 268
 269 /* Other helpers */
 270 LPITEMIDLIST    _ILCreateMyComputer (void);
 271 LPITEMIDLIST    _ILCreateMyDocuments    (void);
 272 LPITEMIDLIST    _ILCreateIExplore   (void);
 273 LPITEMIDLIST    _ILCreateControlPanel   (void);
 274 LPITEMIDLIST    _ILCreatePrinters   (void);
 275 LPITEMIDLIST    _ILCreateNetwork    (void);
 276 LPITEMIDLIST    _ILCreateNetHood    (void);
 277 LPITEMIDLIST    _ILCreateAdminTools (void);
 278 LPITEMIDLIST    _ILCreateFont       (void);
 279 LPITEMIDLIST    _ILCreateBitBucket  (void);
 280 LPITEMIDLIST    _ILCreateDrive      (LPCWSTR);
 281
 282 /*
 283  * helper functions (getting struct-pointer)
 284  */
 285 LPPIDLDATA  _ILGetDataPointer   (LPCITEMIDLIST);
 286 LPSTR       _ILGetTextPointer   (LPCITEMIDLIST);
 287 IID     *_ILGetGUIDPointer  (LPCITEMIDLIST pidl);
 288 FileStructW     *_ILGetFileStructW      (LPCITEMIDLIST pidl);
 289
 290 /*
 291  * debug helper
 292  */
 293 void    pdump   (LPCITEMIDLIST pidl);
 294 BOOL    pcheck  (LPCITEMIDLIST pidl);
 295
 296 /*
 297  * aPidl helper
 298  */
 299 void _ILFreeaPidl(LPITEMIDLIST * apidl, UINT cidl);
 300 LPITEMIDLIST * _ILCopyaPidl(const LPCITEMIDLIST * apidlsrc, UINT cidl);
 301 LPITEMIDLIST * _ILCopyCidaToaPidl(LPITEMIDLIST* pidl, const CIDA * cida);
 302
 303 BOOL WINAPI ILGetDisplayNameExW(LPSHELLFOLDER psf, LPCITEMIDLIST pidl, LPWSTR path, DWORD type);
 304
 305 #endif /* __WINE_PIDL_H */