| 1 | :userdoc.
|
|---|
| 2 |
|
|---|
| 3 | :docprof.
|
|---|
| 4 |
|
|---|
| 5 | :title.WPS undocumented features
|
|---|
| 6 |
|
|---|
| 7 | :h1 res=100.Introduction
|
|---|
| 8 | :p.
|
|---|
| 9 | This document describes features and data structures of the WPS not documented in the official reference manuals. The
|
|---|
| 10 | information was gathered from usegroups, public source code or by means of reverse engineering.
|
|---|
| 11 | :p.
|
|---|
| 12 |
|
|---|
| 13 |
|
|---|
| 14 | :h1 res=3000
|
|---|
| 15 | x=left y=bottom..CLASSINFO
|
|---|
| 16 | :p.
|
|---|
| 17 | The .CLASSINFO extended attribute of filesystem objects contains all the settings of the specific object you
|
|---|
| 18 | may change using the settings notebook. This EA tells the WPS which folder class a folder is an instance of and it
|
|---|
| 19 | contains all the objects instance data saved using _wpSaveXXX().
|
|---|
| 20 | :nt.
|
|---|
| 21 | All data is stored in INTEL byte order in the EA, this means lowByte-HighByte.
|
|---|
| 22 | See examples.
|
|---|
| 23 | :ent.
|
|---|
| 24 |
|
|---|
| 25 | :h2 res=3100
|
|---|
| 26 | x=left width=100%
|
|---|
| 27 | group=2
|
|---|
| 28 | .General data structures
|
|---|
| 29 |
|
|---|
| 30 | :xmp.
|
|---|
| 31 | #define INSTANCEDATA_TYPE_LONG 0x0002
|
|---|
| 32 | #define INSTANCEDATA_TYPE_STRING 0x0003
|
|---|
| 33 | #define INSTANCEDATA_TYPE_BINARY 0x0004
|
|---|
| 34 | :exmp.
|
|---|
| 35 |
|
|---|
| 36 | :xmp.
|
|---|
| 37 | /* Every block of instance data starts with this struct.
|
|---|
| 38 | The data follows directly after this header. */
|
|---|
| 39 | typedef struct _InstanceDataHead
|
|---|
| 40 | {
|
|---|
| 41 | USHORT usType; /* One of the INSTANCEDATA_TYPE_* constants */
|
|---|
| 42 | USHORT usKey; /* key used in wpSaveXXX() */
|
|---|
| 43 | USHORT usLength; /* size of data following */
|
|---|
| 44 | }INSTANCEDATAHEAD;
|
|---|
| 45 | :exmp.
|
|---|
| 46 |
|
|---|
| 47 | :xmp.
|
|---|
| 48 | /* The following structs represent the different types
|
|---|
| 49 | of instance data */
|
|---|
| 50 | typedef struct _wpInstanceDataLong
|
|---|
| 51 | {
|
|---|
| 52 | USHORT usType; /* 0x0002 */
|
|---|
| 53 | USHORT usKey; /* key used in wpSaveLong() */
|
|---|
| 54 | USHORT usLength; /* size of value, always 0x0004 */
|
|---|
| 55 | LONG lValue; /* Data */
|
|---|
| 56 | }INSTANCEDATALONG;
|
|---|
| 57 |
|
|---|
| 58 |
|
|---|
| 59 | typedef struct _wpInstanceDataString
|
|---|
| 60 | {
|
|---|
| 61 | USHORT usType; /* 0x0003 */
|
|---|
| 62 | USHORT usKey; /* key used in wpSaveString() */
|
|---|
| 63 | USHORT usLength; /* String length including terminating 0 */
|
|---|
| 64 | UCHAR ucData[]; /* The string including a terminating 0 */
|
|---|
| 65 | }INSTANCEDATASTRING;
|
|---|
| 66 |
|
|---|
| 67 |
|
|---|
| 68 | typedef struct _wpInstanceDataBinary
|
|---|
| 69 | {
|
|---|
| 70 | USHORT usType; /* 0x0004 */
|
|---|
| 71 | USHORT usKey; /* key used in wpSaveData() */
|
|---|
| 72 | USHORT usLength; /* Size of data block */
|
|---|
| 73 | BYTE data[]; /* Data */
|
|---|
| 74 | }INSTANCEDATABINARY;
|
|---|
| 75 | :exmp.
|
|---|
| 76 |
|
|---|
| 77 | :xmp.
|
|---|
| 78 | /* Instance data block for a class. For every class in the chain of classes
|
|---|
| 79 | there may be one of these blocks. The current class is the first, the parent class
|
|---|
| 80 | instance data follows, then the grand parent class instance data etc. Last one is
|
|---|
| 81 | always WPObject. Directly after this header the data follows. Each data entity consists
|
|---|
| 82 | of an INSTANCEDATAHEAD followed by the associated data as described above. */
|
|---|
| 83 | typedef struct _InstanceDataBlockHead
|
|---|
| 84 | {
|
|---|
| 85 | USHORT usClassNameLength; /* Length of class name including terminating 0 */
|
|---|
| 86 | USHORT usDataSize; /* Size of data block starting after this structure */
|
|---|
| 87 | UCHAR ucClassName[]; /* Array holding name with terminating 0 used during saving.
|
|---|
| 88 | Usually the classname but that's not enforced. */
|
|---|
| 89 |
|
|---|
| 90 | }IDATABLOCKHEAD;
|
|---|
| 91 | :exmp.
|
|---|
| 92 |
|
|---|
| 93 | :xmp.
|
|---|
| 94 | /* Structure of the .CLASSINFO attribute */
|
|---|
| 95 | struct CLASSINFO
|
|---|
| 96 | {
|
|---|
| 97 | const USHORT usEAType; /* Always EAT_BINARY: 0xFFFE */
|
|---|
| 98 | USHORT usSize; /* Size of data starting with usUnknown1 */
|
|---|
| 99 | USHORT usFlags1; /* 0x0000: data files (?) */
|
|---|
| 100 | /* 0x0080: folder (?) */
|
|---|
| 101 | /* 0x0090: folder with custom icon (set using settings notebook) */
|
|---|
| 102 | /* 0x00C8: desktop folder (?) */
|
|---|
| 103 | /* 0x0BD2: WPVault */
|
|---|
| 104 | USHORT usFlags2; /* 0x0000: ?? */
|
|---|
| 105 | /* 0x0001: ?? */
|
|---|
| 106 | USHORT usDataSize; /* Data size following the class name (starting with usOffset) */
|
|---|
| 107 | USHORT usUnknown3;
|
|---|
| 108 | UCHAR ucClassName[]; /* The class of this object including the terminating 0, e.g. WPDataFile */
|
|---|
| 109 | USHORT usOffset; /* Offset to WPObject instance data block starting at usOffset */
|
|---|
| 110 | USHORT usUnknown4; /* */
|
|---|
| 111 | USHORT usUnknown5; /* */
|
|---|
| 112 | USHORT usUnknown6; /* Always the same as usUnknown4 */
|
|---|
| 113 | USHORT usSizeInstanceData; /* Size of all INSTANCEDATABLOCKs + sizeof(usSizeInstanceData2) + sizeof(usUnknown6)
|
|---|
| 114 | + sizeof(usUnknown7) + sizeof(usUnknown8) + sizeof(usSizeInstanceData) */
|
|---|
| 115 | USHORT usUnknown7; /* Always the same as usUnknown4 */
|
|---|
| 116 | USHORT usSizeInstanceData2; /* Size of all INSTANCEDATABLOCKs including 6 terminating zero bytes.
|
|---|
| 117 | Each INSTANCEDATABLOCK structure is followed by a data block of variable length. */
|
|---|
| 118 | USHORT usUnknown8; /* Seems to be alway 0x0000 (?) */
|
|---|
| 119 | INSTANCEDATABLOCK instanceDataBlocks[]; /* One or more instance data blocks. At least the WPObject data block
|
|---|
| 120 | is present. */
|
|---|
| 121 | /* The WPObject instance data block is always the last one. Attention: the instance
|
|---|
| 122 | data blocks may have different sizes! */
|
|---|
| 123 | const UCHAR ucZero[6]; /* 6 terminating zero bytes */
|
|---|
| 124 | }
|
|---|
| 125 | :exmp.
|
|---|
| 126 |
|
|---|
| 127 | :h2 res=3200
|
|---|
| 128 | x=left width=100%
|
|---|
| 129 | group=2
|
|---|
| 130 | .Instance data
|
|---|
| 131 | :p.
|
|---|
| 132 |
|
|---|
| 133 | :h3 res=3300
|
|---|
| 134 | x=left width=100%
|
|---|
| 135 | group=2
|
|---|
| 136 | .Key 0x0b73 (2931), IDKEY_FDRLONGARRAY; WPFolder
|
|---|
| 137 |
|
|---|
| 138 | :xmp.
|
|---|
| 139 | Type 0x0004 (binary)
|
|---|
| 140 | Size 0x54 (84)
|
|---|
| 141 | :exmp.
|
|---|
| 142 | The data can be represented by the following structure (items with ??? are taken from the WPTool source by H. Kelder and are not checked):
|
|---|
| 143 | :xmp.
|
|---|
| 144 | typedef struct _WPFolderLongArray
|
|---|
| 145 | {
|
|---|
| 146 | ULONG ulIconView;
|
|---|
| 147 | ULONG ulTreeView;
|
|---|
| 148 | ULONG ulDetailsView; (???)
|
|---|
| 149 | ULONG ulFolderFlag; (???)
|
|---|
| 150 | ULONG ulUnknown1;
|
|---|
| 151 | ULONG ulUnknown2;
|
|---|
| 152 | BYTE rgbTextBkgnd[4];
|
|---|
| 153 | BYTE Filler1[4];
|
|---|
| 154 | BYTE Filler2[4];
|
|---|
| 155 | BYTE rgbIconTextColor[4];
|
|---|
| 156 | BYTE Filler3[4];
|
|---|
| 157 | BYTE rgbTreeTextColor[4];
|
|---|
| 158 | BYTE rgbDetailsTextColor[4];
|
|---|
| 159 | BYTE Filler5[4];
|
|---|
| 160 | BYTE Filler6[4];
|
|---|
| 161 | BYTE Filler7[4];
|
|---|
| 162 | BYTE Filler8[4];
|
|---|
| 163 | ULONG ulMenuFlag; (???)
|
|---|
| 164 | BYTE rgbIconShadowTextColor[4];
|
|---|
| 165 | BYTE rgbTreeShadowTextColor[4];
|
|---|
| 166 | BYTE rgbDetailsShadowTextColor[4];
|
|---|
| 167 |
|
|---|
| 168 | } WPFOLDLONGARRAY;
|
|---|
| 169 | :exmp.
|
|---|
| 170 |
|
|---|
| 171 | :xmp.
|
|---|
| 172 | Example:
|
|---|
| 173 |
|
|---|
| 174 | 00 00 04 00 73 0B 54 00 80 00 30 00 64 00 50 00
|
|---|
| 175 | ^^^^^ ^^^^^ ^^^^^ ^^ ^^ ^^
|
|---|
| 176 | | | | | | |
|
|---|
| 177 | | | | | | View (2. Tree): 0x50: with lines
|
|---|
| 178 | | | | | | 0x10: without lines
|
|---|
| 179 | | | | | Tree Icon: 0x64: small
|
|---|
| 180 | | | | | 0x44: normal
|
|---|
| 181 | | | | | 0x41: invisible
|
|---|
| 182 | | | | |
|
|---|
| 183 | | | | View (first view page): 22h: Non flowed, single column, small icons
|
|---|
| 184 | | | | 02h: Non flowed, single column, normal icons
|
|---|
| 185 | | | | 01h: Non flowed, single column, invisible icons
|
|---|
| 186 | | | | 32h: Non flowed, multiple columns, small icons
|
|---|
| 187 | | | | 12h: Non flowed, multiple columns, normal icons
|
|---|
| 188 | | | | 11h: Non flowed, multiple columns, invisible icons
|
|---|
| 189 | | | Size (84 dec) 04h: Flowed as placed normal icons
|
|---|
| 190 | | | 24h: Flowed as placed small icons
|
|---|
| 191 | | Key 80h: Gridded
|
|---|
| 192 | Binary
|
|---|
| 193 |
|
|---|
| 194 | 08 80 30 00 03 00 00 00 00 00 00 00 FF FF FF FF
|
|---|
| 195 |
|
|---|
| 196 | 55 55 80 40 EF FF FF FF EF FF FF FF DD FF FF FF <--- 0xFF if not changed
|
|---|
| 197 | ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^--> Icon text color
|
|---|
| 198 | | | | |
|
|---|
| 199 | | | | 0x40 if color never set, after setting 0x00. If 0xff apparently use system default.
|
|---|
| 200 | | | R |
|
|---|
| 201 | | G | |
|
|---|
| 202 | B | | |
|
|---|
| 203 | | | | |
|
|---|
| 204 | ------------> Text background for every view. If set to transparency: 0xFFFFFF01
|
|---|
| 205 | |
|
|---|
| 206 | 01 if Transparent
|
|---|
| 207 |
|
|---|
| 208 | EF FF FF FF EF FF FF FF DD FF FF FF 00 00 00 40
|
|---|
| 209 | ^^ ^^ ^^ ^^
|
|---|
| 210 | |_________|
|
|---|
| 211 | |
|
|---|
| 212 | Tree text color (init: 0xFFFFFFEF)
|
|---|
| 213 |
|
|---|
| 214 | 00 00 00 40 00 00 00 40 00 00 00 00 02 00 00 00
|
|---|
| 215 |
|
|---|
| 216 |
|
|---|
| 217 | D0 FF FF FF D0 FF FF FF D0 FF FF FF 04 00 74 0B
|
|---|
| 218 | ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^ ^^
|
|---|
| 219 | | | | | | | | | |_________|--Details shadow text color
|
|---|
| 220 | | | | | | | | | |
|
|---|
| 221 | | | | | | | | | Last byte
|
|---|
| 222 | | | | | | | | |
|
|---|
| 223 | | | | | | | | 0xFF if not changed
|
|---|
| 224 | | | | | | | R
|
|---|
| 225 | | | | | | G
|
|---|
| 226 | | | | | B
|
|---|
| 227 | | | | | |________|-- Tree shadow text color
|
|---|
| 228 | | | | |
|
|---|
| 229 | | | | |
|
|---|
| 230 | | | | 0xFF if not changed
|
|---|
| 231 | | | R
|
|---|
| 232 | | G
|
|---|
| 233 | B |
|
|---|
| 234 | |________|-- Icon shadow text color
|
|---|
| 235 | :exmp.
|
|---|
| 236 |
|
|---|
| 237 |
|
|---|
| 238 | :h3 res=3600
|
|---|
| 239 | x=left width=100%
|
|---|
| 240 | group=2
|
|---|
| 241 | .Key 0x04 (4), WPObject
|
|---|
| 242 | :p.
|
|---|
| 243 | This key is always at the end of the .CLASSINFO data. It is followed by the 6 terminating zeros.
|
|---|
| 244 | :xmp.
|
|---|
| 245 | Type 0x0004
|
|---|
| 246 | Size 0x08
|
|---|
| 247 | struct _WPObjectKey04
|
|---|
| 248 | {
|
|---|
| 249 | BYTE bytes[8]; /* Seems to be most of the time 0xFFFFFFFF FFFFFFFF
|
|---|
| 250 | but sometimes has indeed another value. */
|
|---|
| 251 | }
|
|---|
| 252 | :exmp.
|
|---|
| 253 |
|
|---|
| 254 | :h3 res=3400
|
|---|
| 255 | x=left width=100%
|
|---|
| 256 | group=2
|
|---|
| 257 | .Key 0x0b (11), WPObject data
|
|---|
| 258 | :p.
|
|---|
| 259 | This info is from the WPTOOL source by H. Kelder. Items with (??) are not checked for accuracy.
|
|---|
| 260 | :xmp.
|
|---|
| 261 | Type 0x0004
|
|---|
| 262 | Size 0x20 (32)
|
|---|
| 263 |
|
|---|
| 264 | struct _WPObjectData
|
|---|
| 265 | {
|
|---|
| 266 | LONG lDefaultView; /* As set in the settings notebook e.g 102: Details view (OPEN_DETAILS) */
|
|---|
| 267 | ULONG ulHelpPanel; (??)
|
|---|
| 268 | ULONG ulUnknown3; (??)
|
|---|
| 269 | ULONG ulObjectStyle; /* Different OBJSTYLE_* ored together */
|
|---|
| 270 | ULONG ulMinWin; (??)
|
|---|
| 271 | ULONG ulConcurrent; (??)
|
|---|
| 272 | ULONG ulViewButton; (??)
|
|---|
| 273 | ULONG ulMenuFlag; /* Short menus: 0x00000000, normal (long): 0x00000001 */
|
|---|
| 274 | } WPOBJDATA;
|
|---|
| 275 | :exmp.
|
|---|
| 276 |
|
|---|
| 277 | :h3 res=3500
|
|---|
| 278 | x=left width=100%
|
|---|
| 279 | group=2
|
|---|
| 280 | .Key 0x0c (12), WPObject
|
|---|
| 281 | :p.
|
|---|
| 282 | Contains the ID if set and additional data, probably the object handle.
|
|---|
| 283 | :xmp.
|
|---|
| 284 | Type 0x0004
|
|---|
| 285 | Size 0x02 when empty, data is 0xFFFF
|
|---|
| 286 | 0xXX when data saved.
|
|---|
| 287 |
|
|---|
| 288 | struct _WPObjectDataKey0C_1
|
|---|
| 289 | {
|
|---|
| 290 | USHORT usType; /* 0x0001 */
|
|---|
| 291 | UCHAR ucID[]; /* ID with terminating 0 */
|
|---|
| 292 | }
|
|---|
| 293 | :exmp.
|
|---|
| 294 | :p.
|
|---|
| 295 | This structure may be followed (but isn't always) by another one. Or the second one is the only
|
|---|
| 296 | structure if the object doesn't has an ID but a handle.
|
|---|
| 297 | :p.
|
|---|
| 298 | :xmp.
|
|---|
| 299 | struct _WPObjectDataKey0C_2
|
|---|
| 300 | {
|
|---|
| 301 | USHORT usType; /* 0x0002 */
|
|---|
| 302 | UCHAR ucHandle[]; /* Apparently handle(s) in decimal followed by an ID value,
|
|---|
| 303 | terminated with 0. e.g. 206526@10. Several handles with ID
|
|---|
| 304 | separated by ',' may be found. The handle is always the same
|
|---|
| 305 | (of course) but the ID different, e.g. 251239@10,251239@20.
|
|---|
| 306 | The ID probably specifies icon/details/tree view. I guess
|
|---|
| 307 | this is added when a folder position record is added to the INI.
|
|---|
| 308 | XXXXXX@YY is the key in the INI then.
|
|---|
| 309 | @1010: tree view
|
|---|
| 310 | @10:
|
|---|
| 311 | @20: */
|
|---|
| 312 | }
|
|---|
| 313 | :exmp.
|
|---|
| 314 | :p.
|
|---|
| 315 | The structure(s) are always followed by 0xFFFF. If the key is 'empty' only this
|
|---|
| 316 | value is stored. The 0xFFFF is included in the size.
|
|---|
| 317 | :p.
|
|---|
| 318 | :xmp.
|
|---|
| 319 | USHORT usPad[2]; /* Always 0xFFFF. Always appended. */
|
|---|
| 320 | :exmp.
|
|---|
| 321 |
|
|---|
| 322 | .********************** methods ************************
|
|---|
| 323 | :h1 res=4000
|
|---|
| 324 | x=left y=bottom width=100%.Methods
|
|---|
| 325 |
|
|---|
| 326 |
|
|---|
| 327 | :h2 res=4010
|
|---|
| 328 | x=left y=bottom width=100%.wpMakeDormant
|
|---|
| 329 |
|
|---|
| 330 | :xmp.
|
|---|
| 331 | This can fail if the object is locked by system for some reason e.g. running executables.
|
|---|
| 332 |
|
|---|
| 333 | BOOL wpDestroyObject();
|
|---|
| 334 |
|
|---|
| 335 |
|
|---|
| 336 | :exmp.
|
|---|
| 337 | :xmp.
|
|---|
| 338 | BOOL wpMakeDormant(in BOOL fSave)
|
|---|
| 339 |
|
|---|
| 340 | // finally, this calls wpMakeDormant, which destroys the SOM object
|
|---|
| 341 | brc = _wpMakeDormant(somSelf, 0);
|
|---|
| 342 |
|
|---|
| 343 | /*
|
|---|
| 344 | *@@sourcefile object.c
|
|---|
| 345 | * implementation code for XFldObject class.
|
|---|
| 346 | *
|
|---|
| 347 | * This file is ALL new with V0.9.0.
|
|---|
| 348 | *
|
|---|
| 349 | * This looks like a good place for general explanations
|
|---|
| 350 | * about how the WPS maintains Desktop objects as SOM objects
|
|---|
| 351 | * in memory.
|
|---|
| 352 | *
|
|---|
| 353 | * The basic object life cycle is like this:
|
|---|
| 354 | *
|
|---|
| 355 | + wpclsNew
|
|---|
| 356 | + wpCopyObject
|
|---|
| 357 | + wpCreateFromTemplate
|
|---|
| 358 | + ³
|
|---|
| 359 | + ³ ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
|
|---|
| 360 | + ³ ³ awake object ³
|
|---|
| 361 | + ÀÄÄÄÄ> ³ (physical ³ <ÄÄ wpclsMakeAwake ÄÄÄ¿
|
|---|
| 362 | + ³ and memory) ³ ³
|
|---|
| 363 | + ÀÄÄÄÄÄÂÄÂÄÄÄÄÄÄÙ ³
|
|---|
| 364 | + ³ ³ ³
|
|---|
| 365 | + \ / ³ ³ ÚÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄ¿
|
|---|
| 366 | + X <ÄÄ wpFree ÄÙ ÀÄ wpMakeDormant Ä> ³ dormant object ³
|
|---|
| 367 | + / \ ³ (physical only)³
|
|---|
| 368 | + ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
|
|---|
| 369 | *
|
|---|
| 370 | * The basic rule is that there is the concept of a
|
|---|
| 371 | * "dormant object". This is an object that currently
|
|---|
| 372 | * exists only in storage, but not as a SOM object in
|
|---|
| 373 | * memory. "Storage" is disk for file-system objects
|
|---|
| 374 | * and OS2.INI for abstract objects.
|
|---|
| 375 | *
|
|---|
| 376 | * By contrast, an object is said to be "awake" if it
|
|---|
| 377 | * also exists as a SOM object in memory. Per definition,
|
|---|
| 378 | * an awake object also has a physical representation.
|
|---|
| 379 | * Only WPTransients have no physical storage at all;
|
|---|
| 380 | * as a consequence, there is really no such thing as
|
|---|
| 381 | * a dormant transient object.
|
|---|
| 382 | *
|
|---|
| 383 | * 1) Objects are most frequently made awake when a folder
|
|---|
| 384 | * is populated (mostly on folder open). Of course this
|
|---|
| 385 | * does not physically create objects... they are only
|
|---|
| 386 | * instantiated in memory then from their physical
|
|---|
| 387 | * storage.
|
|---|
| 388 | *
|
|---|
| 389 | * There are many ways to awake objects. To awake a
|
|---|
| 390 | * single object, call M_WPObject&colon.&colon.wpclsMakeAwake.
|
|---|
| 391 | * This is a bit difficult to manage, so
|
|---|
| 392 | * WPFileSystem&colon.&colon.wpclsQueryObjectFromPath is easier
|
|---|
| 393 | * for waking up FS objects (which calls wpclsMakeAwake
|
|---|
| 394 | * internally). wpclsMakeAwake also gets called from
|
|---|
| 395 | * within WPFolder&colon.&colon.wpPopulate.
|
|---|
| 396 | *
|
|---|
| 397 | * 2) Even though this isn't documented anywhere, the
|
|---|
| 398 | * WPS also supports the reverse concept of making
|
|---|
| 399 | * the object dormant again. This will destroy the
|
|---|
| 400 | * SOM object in memory, but not the physical representation.
|
|---|
| 401 | *
|
|---|
| 402 | * I suspect this was not documented because you can
|
|---|
| 403 | * never know whether some code still needs the
|
|---|
| 404 | * SOM pointer to the object somehow. Anyway, the
|
|---|
| 405 | * WPS _does_ make objects dormant again, e.g. when
|
|---|
| 406 | * their folders are closed and they are not referenced
|
|---|
| 407 | * from anywhere else. You can prevent the WPS from doing
|
|---|
| 408 | * this by calling WPObject&colon.&colon.wpLock.
|
|---|
| 409 | *
|
|---|
| 410 | * The interesting thing is that there is an undocumented
|
|---|
| 411 | * method for destroying the SOM object.
|
|---|
| 412 | * WPObject&colon.&colon.wpMakeDormant does exactly this.
|
|---|
| 413 | * Actually, this does a lot of things:
|
|---|
| 414 | *
|
|---|
| 415 | * -- It removes the object from all containers,
|
|---|
| 416 | *
|
|---|
| 417 | * -- closes all views (wpClose),
|
|---|
| 418 | *
|
|---|
| 419 | * -- frees all associated memory allocated thru wpAllocMem.
|
|---|
| 420 | *
|
|---|
| 421 | * -- In addition, if the object has called _wpSaveDeferred
|
|---|
| 422 | * and a _wpSaveImmediate is thus pending, _wpSaveImmediate
|
|---|
| 423 | * also gets called. (See XFldObject&colon.&colon.wpSaveDeferred
|
|---|
| 424 | * for more about this.)
|
|---|
| 425 | *
|
|---|
| 426 | * -- Finally, wpMakeDormant calls wpUnInitData, which
|
|---|
| 427 | * should clean up the object.
|
|---|
| 428 | *
|
|---|
| 429 | * 3) An object is physically created through either
|
|---|
| 430 | * M_WPObject&colon.&colon.wpclsNew or WPObject&colon.&colon.wpCopyObject or
|
|---|
| 431 | * WPObject&colon.&colon.wpCreateAnother or WPObject&colon.&colon.wpCreateFromTemplate.
|
|---|
| 432 | * These are the "object factories" of the WPS. Depending
|
|---|
| 433 | * on which class the method is invoked on, the new object
|
|---|
| 434 | * will be of that class.
|
|---|
| 435 | *
|
|---|
| 436 | * Depending on the object's class, wpclsNew will create
|
|---|
| 437 | * a physical representation (e.g. file, folder) of the
|
|---|
| 438 | * object _and_ a SOM object. So calling, for example,
|
|---|
| 439 | * M_WPFolder&colon.&colon.wpclsNew will create a new folder on disk
|
|---|
| 440 | * and return a SOM object that represents it.
|
|---|
| 441 | *
|
|---|
| 442 | * 4) Deleting an object can really be done in two ways:
|
|---|
| 443 | *
|
|---|
| 444 | * -- WPObject&colon.&colon.wpDelete looks like the most natural
|
|---|
| 445 | * way. However this really only displays a
|
|---|
| 446 | * confirmation and then invokes WPObject&colon.&colon.wpFree.
|
|---|
| 447 | *
|
|---|
| 448 | * -- WPObject&colon.&colon.wpFree is the most direct way to
|
|---|
| 449 | * delete an object. This does not display any
|
|---|
| 450 | * more confirmations (in theory), but deletes
|
|---|
| 451 | * the object right away.
|
|---|
| 452 | *
|
|---|
| 453 | * Interestingly, wpFree in turn calls another
|
|---|
| 454 | * undocumented method -- WPObject&colon.&colon.wpDestroyObject.
|
|---|
| 455 | * From my testing this is responsible for destroying
|
|---|
| 456 | * the physical representation (file, folder, INI data).
|
|---|
| 457 | *
|
|---|
| 458 | * After that, wpFree also calls wpMakeDormant
|
|---|
| 459 | * to free the SOM object.
|
|---|
| 460 | *
|
|---|
| 461 | * wpDestroyObject is a bit obscure. I believe it is this
|
|---|
| 462 | * method which was supposed to do the object cleanup.
|
|---|
| 463 | * It is introduced by WPObject and overridden by the
|
|---|
| 464 | * following classes:
|
|---|
| 465 | *
|
|---|
| 466 | * -- WPFileSystem&colon. apparently, this then does DosDelete.
|
|---|
| 467 | * Unfortunately, this one has a real nasty bug... it
|
|---|
| 468 | * displays a message box if deleting the object fails.
|
|---|
| 469 | * This is really annoying when calling wpFree in a loop
|
|---|
| 470 | * on a bunch of objects. That's why we override this
|
|---|
| 471 | * method in WPDataFile&colon.&colon.wpDestroyObject and similar
|
|---|
| 472 | * methods (V0.9.20).
|
|---|
| 473 | *
|
|---|
| 474 | * -- WPAbstract&colon. this probably removes the INI entries
|
|---|
| 475 | * associated with the abstract object.
|
|---|
| 476 | *
|
|---|
| 477 | * -- WPProgram.
|
|---|
| 478 | *
|
|---|
| 479 | * -- WPProgramFile.
|
|---|
| 480 | *
|
|---|
| 481 | * -- WPTransient.
|
|---|
| 482 | *
|
|---|
| 483 | * If folder auto-refresh is replaced by XWP, we must override
|
|---|
| 484 | * wpFree in order to suppress calling this method. The message
|
|---|
| 485 | * box bug is not acceptable for file-system objects, so we have
|
|---|
| 486 | * introduced WPDataFile&colon.&colon.wpDestroyObject instead.
|
|---|
| 487 | *
|
|---|
| 488 | * The destruction call sequence thus is&colon.&colon.
|
|---|
| 489 | *
|
|---|
| 490 | + wpDelete (display confirmation, if applicable)
|
|---|
| 491 | + |
|
|---|
| 492 | + +-- wpFree (really delete the object now)
|
|---|
| 493 | + |
|
|---|
| 494 | + +-- wpDestroyObject (delete physical storage)
|
|---|
| 495 | + |
|
|---|
| 496 | + +-- wpMakeDormant (delete SOM object in memory)
|
|---|
| 497 | + |
|
|---|
| 498 | + +-- (lots of cleanup: wpClose, etc.)
|
|---|
| 499 | + |
|
|---|
| 500 | + +-- wpSaveImmediate (if "dirty")
|
|---|
| 501 | + |
|
|---|
| 502 | + +-- wpUnInitData
|
|---|
| 503 | *
|
|---|
| 504 | * Function prefix for this file:
|
|---|
| 505 | * -- obj*
|
|---|
| 506 | *
|
|---|
| 507 | *@@added V0.9.0 [umoeller]
|
|---|
| 508 | *@@header "filesys\object.h"
|
|---|
| 509 | */
|
|---|
| 510 | :exmp.
|
|---|
| 511 |
|
|---|
| 512 |
|
|---|
| 513 | :h2 res=4020
|
|---|
| 514 | x=left y=bottom width=100%.wpRefresh
|
|---|
| 515 | :p.
|
|---|
| 516 | If the menu item "refresh" is selected, wpRefresh(ULONG ulView, PVOID pReserved) is called with
|
|---|
| 517 | ulView==0.
|
|---|
| 518 | :p.
|
|---|
| 519 | If any of the "change to" menu items is selected (details, contents...), ulView will be the selected view.
|
|---|
| 520 |
|
|---|
| 521 |
|
|---|
| 522 | .********************** Setup Strings ************************
|
|---|
| 523 | :h1 res=2000
|
|---|
| 524 | x=left y=bottom width=30%.Setup strings
|
|---|
| 525 | :p.
|
|---|
| 526 | The following setup strings are more or less undocumented.
|
|---|
| 527 | :ul.
|
|---|
| 528 | :li.:link reftype=hd res=2010.SAVEALLICONPOS:elink.
|
|---|
| 529 |
|
|---|
| 530 | :eul.
|
|---|
| 531 |
|
|---|
| 532 | :h2 res=2010
|
|---|
| 533 | x=30% width=70%
|
|---|
| 534 | group=2
|
|---|
| 535 | .SAVEALLICONPOS
|
|---|
| 536 | :p.
|
|---|
| 537 | Force a folder to save the icon positions of all it's objects. Seems to work at least with the desktop. May
|
|---|
| 538 | also work with every other folder class.
|
|---|
| 539 | :xmp.
|
|---|
| 540 | SysSetObjectData("<WP_DESKTOP>"," SAVEALLICONPOS=YES")
|
|---|
| 541 | :exmp.
|
|---|
| 542 |
|
|---|
| 543 |
|
|---|
| 544 | .********************** random stuff ************************
|
|---|
| 545 | :h1 res=5000
|
|---|
| 546 | x=left y=bottom width=100%.Other observations
|
|---|
| 547 | :p.
|
|---|
| 548 | :ul.
|
|---|
| 549 | :li.wpQueryDetailsData() is always called before wpObjectReady()
|
|---|
| 550 | :li.wpRestoreData() is called before wpQueryDetailsData()
|
|---|
| 551 |
|
|---|
| 552 | :eul.
|
|---|
| 553 | :euserdoc.
|
|---|
| 554 |
|
|---|
| 555 |
|
|---|
| 556 |
|
|---|
| 557 |
|
|---|
| 558 |
|
|---|
| 559 |
|
|---|
| 560 |
|
|---|
| 561 |
|
|---|
| 562 |
|
|---|
