dlls/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 #include <stdarg.h>
  39
  40 #include "windef.h"
  41 #include "winbase.h"
  42 #include "winuser.h"
  43 #include "shlobj.h"
  44
  45 /*
  46 * the pidl does cache fileattributes to speed up SHGetAttributes when
  47 * displaying a big number of files.
  48 *
  49 * a pidl of NULL means the desktop
  50 *
  51 * The structure of the pidl seems to be a union. The first byte of the
  52 * PIDLDATA desribes the type of pidl.
  53 *
  54 *       object        ! first byte /  ! format       ! living space
  55 *                     ! size
  56 *       ----------------------------------------------------------------
  57 *       my computer     0x1F/20         guid (2)        (usual)
  58 *       network         0x1F            guid
  59 *       bitbucket       0x1F            guid
  60 *       drive           0x23/25         drive           (usual)
  61 *       drive           0x25/25         drive           (lnk/persistent)
  62 *       drive           0x29/25         drive
  63 *       shell extension 0x2E            guid
  64 *       drive           0x2F            drive           (lnk/persistent)
  65 *       folder/file     0x30            folder/file (1) (lnk/persistent)
  66 *       folder          0x31            folder          (usual)
  67 *       valueA          0x32            file            (ANSI file name)
  68 *       valueW          0x34            file            (Unicode file name)
  69 *       workgroup       0x41            network (3)
  70 *       computer        0x42            network (4)
  71 *       net provider    0x46            network
  72 *       whole network   0x47            network (5)
  73 *       MSITStore       0x61            htmlhlp (7)
  74 *       printers/ras connections        0x70            guid
  75 *       history/favorites 0xb1          file
  76 *       share           0xc3            network (6)
  77 *
  78 * guess: the persistent elements are non tracking
  79 *
  80 * (1) dummy byte is used, attributes are empty
  81 * (2) IID_MyComputer = 20D04FE0L-3AEA-1069-A2D8-08002B30309D
  82 * (3) two strings       "workgroup" "Microsoft Network"
  83 * (4) two strings       "\\sirius" "Microsoft Network"
  84 * (5) one string        "Entire Network"
  85 * (6) two strings       "\\sirius\c" "Microsoft Network"
  86 * (7) contains string   "mk:@MSITStore:C:\path\file.chm::/path/filename.htm"
  87 *               GUID    871C5380-42A0-1069-A2EA-08002B30309D
  88 */
  89
  90 #define PT_CPLAPPLET    0x00
  91 #define PT_GUID         0x1F
  92 #define PT_DRIVE        0x23
  93 #define PT_DRIVE2       0x25
  94 #define PT_DRIVE3       0x29
  95 #define PT_SHELLEXT     0x2E
  96 #define PT_DRIVE1       0x2F
  97 #define PT_FOLDER1      0x30
  98 #define PT_FOLDER       0x31
  99 #define PT_VALUE        0x32
 100 #define PT_VALUEW       0x34
 101 #define PT_WORKGRP      0x41
 102 #define PT_COMP         0x42
 103 #define PT_NETPROVIDER  0x46
 104 #define PT_NETWORK      0x47
 105 #define PT_IESPECIAL1   0x61
 106 #define PT_YAGUID       0x70 /* yet another guid.. */
 107 #define PT_IESPECIAL2   0xb1
 108 #define PT_SHARE        0xc3
 109
 110 #include "pshpack1.h"
 111 typedef BYTE PIDLTYPE;
 112
 113 typedef struct tagPIDLCPanelStruct
 114 {
 115     BYTE dummy;                 /*01 is 0x00 */
 116     DWORD iconIdx;              /*02 negative icon ID */
 117     WORD offsDispName;          /*06*/
 118     WORD offsComment;           /*08*/
 119     CHAR szName[1];             /*10*/ /* terminated by 0x00, followed by display name and comment string */
 120 } PIDLCPanelStruct;
 121
 122 typedef struct tagGUIDStruct
 123 {
 124     BYTE dummy; /* offset 01 is unknown */
 125     GUID guid;  /* offset 02 */
 126 } GUIDStruct;
 127
 128 typedef struct tagDriveStruct
 129 {
 130     CHAR szDriveName[20];       /*01*/
 131     WORD unknown;               /*21*/
 132 } DriveStruct;
 133
 134 typedef struct tagFileStruct
 135 {
 136     BYTE dummy;                 /*01 is 0x00 for files or dirs */
 137     DWORD dwFileSize;           /*02*/
 138     WORD uFileDate;             /*06*/
 139     WORD uFileTime;             /*08*/
 140     WORD uFileAttribs;          /*10*/
 141     CHAR szNames[1];            /*12*/
 142     /* Here are coming two strings. The first is the long name.
 143     The second the dos name when needed or just 0x00 */
 144 } FileStruct;
 145
 146 /* At least on WinXP, this struct is appended with 2-byte-alignment to FileStruct. There follows
 147  * a WORD member after the wszName string, which gives the offset from the beginning of the PIDL
 148  * to the FileStructW member. */
 149 typedef struct tagFileStructW {
 150     WORD cbLen;
 151     BYTE dummy1[6];
 152     WORD uCreationDate;
 153     WORD uCreationTime;
 154     WORD uLastAccessDate;
 155     WORD uLastAccessTime;
 156     BYTE dummy2[4];
 157     WCHAR wszName[1];
 158 } FileStructW;
 159
 160 typedef struct tagValueW
 161 {
 162     WCHAR name[1];
 163 } ValueWStruct;
 164
 165 typedef struct tagPIDLDATA
 166 {       PIDLTYPE type;                  /*00*/
 167         union
 168         {
 169           struct tagGUIDStruct guid;
 170           struct tagDriveStruct drive;
 171           struct tagFileStruct file;
 172           struct
 173           { WORD dummy;         /*01*/
 174             CHAR szNames[1];    /*03*/
 175           } network;
 176           struct
 177           { WORD dummy;         /*01*/
 178             DWORD dummy1;       /*02*/
 179             CHAR szName[1];     /*06*/ /* terminated by 0x00 0x00 */
 180           } htmlhelp;
 181           struct tagPIDLCPanelStruct cpanel;
 182           struct tagValueW valueW;
 183         }u;
 184 } PIDLDATA, *LPPIDLDATA;
 185 #include "poppack.h"
 186
 187 /*
 188  * getting special values from simple pidls
 189  */
 190 DWORD   _ILSimpleGetText        (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 191 DWORD   _ILSimpleGetTextW       (LPCITEMIDLIST pidl, LPWSTR pOut, UINT uOutSize);
 192 BOOL    _ILGetFileDate          (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 193 DWORD   _ILGetFileSize          (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 194 BOOL    _ILGetExtension         (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 195 void    _ILGetFileType          (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 196 DWORD   _ILGetFileAttributes    (LPCITEMIDLIST pidl, LPSTR pOut, UINT uOutSize);
 197
 198 BOOL    _ILGetFileDateTime      (LPCITEMIDLIST pidl, FILETIME *ft);
 199 DWORD   _ILGetDrive             (LPCITEMIDLIST, LPSTR, UINT);
 200
 201 /*
 202  * testing simple pidls
 203  */
 204 BOOL    _ILIsUnicode            (LPCITEMIDLIST pidl);
 205 BOOL    _ILIsDesktop            (LPCITEMIDLIST pidl);
 206 BOOL    _ILIsMyComputer         (LPCITEMIDLIST pidl);
 207 BOOL    _ILIsDrive              (LPCITEMIDLIST pidl);
 208 BOOL    _ILIsFolder             (LPCITEMIDLIST pidl);
 209 BOOL    _ILIsValue              (LPCITEMIDLIST pidl);
 210 BOOL    _ILIsSpecialFolder      (LPCITEMIDLIST pidl);
 211 BOOL    _ILIsPidlSimple         (LPCITEMIDLIST pidl);
 212 BOOL    _ILIsCPanelStruct       (LPCITEMIDLIST pidl);
 213 static inline
 214 BOOL    _ILIsEqualSimple        (LPCITEMIDLIST pidlA, LPCITEMIDLIST pidlB)
 215 {
 216     return (pidlA->mkid.cb > 0 && !memcmp(pidlA, pidlB, pidlA->mkid.cb)) ||
 217             (!pidlA->mkid.cb && !pidlB->mkid.cb);
 218 }
 219 static inline
 220 BOOL    _ILIsEmpty              (LPCITEMIDLIST pidl) { return _ILIsDesktop(pidl); }
 221
 222 /*
 223  * simple pidls
 224  */
 225
 226 /* Basic PIDL constructor.  Allocates size + 5 bytes, where:
 227  * - two bytes are SHITEMID.cb
 228  * - one byte is PIDLDATA.type
 229  * - two bytes are the NULL PIDL terminator
 230  * Sets type of the returned PIDL to type.
 231  */
 232 LPITEMIDLIST    _ILAlloc(PIDLTYPE type, unsigned int size);
 233
 234 /* Creates a PIDL with guid format and type type, which must be one of PT_GUID,
 235  * PT_SHELLEXT, or PT_YAGUID.
 236  */
 237 LPITEMIDLIST    _ILCreateGuid(PIDLTYPE type, REFIID guid);
 238
 239 /* Like _ILCreateGuid, but using the string szGUID. */
 240 LPITEMIDLIST    _ILCreateGuidFromStrA(LPCSTR szGUID);
 241 LPITEMIDLIST    _ILCreateGuidFromStrW(LPCWSTR szGUID);
 242
 243 /* Commonly used PIDLs representing file system objects. */
 244 LPITEMIDLIST    _ILCreateDesktop        (void);
 245 LPITEMIDLIST    _ILCreateFromFindDataW(const WIN32_FIND_DATAW *stffile);
 246 HRESULT         _ILCreateFromPathW      (LPCWSTR szPath, LPITEMIDLIST* ppidl);
 247
 248 /* Other helpers */
 249 LPITEMIDLIST    _ILCreateMyComputer     (void);
 250 LPITEMIDLIST    _ILCreateMyDocuments    (void);
 251 LPITEMIDLIST    _ILCreateIExplore       (void);
 252 LPITEMIDLIST    _ILCreateControlPanel   (void);
 253 LPITEMIDLIST    _ILCreatePrinters       (void);
 254 LPITEMIDLIST    _ILCreateNetwork        (void);
 255 LPITEMIDLIST    _ILCreateNetHood        (void);
 256 LPITEMIDLIST    _ILCreateBitBucket      (void);
 257 LPITEMIDLIST    _ILCreateDrive          (LPCWSTR);
 258
 259 /*
 260  * helper functions (getting struct-pointer)
 261  */
 262 LPPIDLDATA      _ILGetDataPointer       (LPCITEMIDLIST);
 263 LPSTR           _ILGetTextPointer       (LPCITEMIDLIST);
 264 LPWSTR          _ILGetTextPointerW      (LPCITEMIDLIST);
 265 LPSTR           _ILGetSTextPointer      (LPCITEMIDLIST);
 266 IID             *_ILGetGUIDPointer      (LPCITEMIDLIST pidl);
 267 FileStructW     *_ILGetFileStructW      (LPCITEMIDLIST pidl);
 268
 269 /*
 270  * debug helper
 271  */
 272 void    pdump   (LPCITEMIDLIST pidl);
 273 BOOL    pcheck  (LPCITEMIDLIST pidl);
 274
 275 /*
 276  * aPidl helper
 277  */
 278 void _ILFreeaPidl(LPITEMIDLIST * apidl, UINT cidl);
 279 LPITEMIDLIST * _ILCopyaPidl(LPCITEMIDLIST * apidlsrc, UINT cidl);
 280 LPITEMIDLIST * _ILCopyCidaToaPidl(LPITEMIDLIST* pidl, LPIDA cida);
 281
 282 BOOL WINAPI ILGetDisplayNameExA(LPSHELLFOLDER psf, LPCITEMIDLIST pidl, LPSTR path, DWORD type);
 283 BOOL WINAPI ILGetDisplayNameExW(LPSHELLFOLDER psf, LPCITEMIDLIST pidl, LPWSTR path, DWORD type);
 284
 285 #endif