Atom Table Functions (Local + Global Atoms)

[Ascend4nt]

Atom Table UDF

Local and Global Atom Table

---

Since I've had this collecting dust on my computer, I figured I'd release it to see if anyone can find some use for it.

About Atom Tables - MSDN

Example Global Atom Table Listing

 

Basically, a bunch of strings can be stored locally (at program level) or globally (at O/S level) with unique numerical identifiers. This UDF lets you add, find, delete, and query these atoms.

 

Description from the top of the AtomFunctions UDF:

----------------------------------------------------------------

Functions for accesing Local and Global Atom Tables, which contain strings up to 255 characters long

The Atom tables are used for multiple types of Windows data including Window Classes (RegisterClass/Ex), Clipboard formats (RegisterClipboardFormat), Hotkeys (RegisterHotKey), and Dynamic Data Exchange (DDE) which is a form of interprocess communication. (Some of the above may use a Local rather than the Global Atom table)

Other uses can include storing program strings to lookup by a 16-bit value and interprocess communication

 "RegisterHotKey function" @ MSDN states this:

 "An application must specify an id value in the range 0x0000 through 0xBFFF.

  A shared DLL must specify a value in the range 0xC000 through 0xFFFF

  (the range returned by the GlobalAddAtom function).

  To avoid conflicts with hot-key identifiers defined by other shared DLLs,

  a DLL should use the GlobalAddAtom function to obtain the hot-key identifier."

 Kernel Note: The Atom Table is a separate entity from Kernel Objects like Events, Mutexes, Files, etc.  However, the Atom Table is (separately) accessible from within the Kernel, so its like a Kernish object?

Notes on Atom Tables:

• Stringlimit is 255 characters NOT including a null-terminator. This is unfortunately not   enough for a MAX_PATH string, which is 259+null-term. However, stripping off root-drive prefix get you within 1 character of the length (259 - 3 ["C:"] = 256] which may be enough - but using IPC, one can store 4 - 6 (8-12 in x64) extra chars in wParam/lParam..   See <AtomExample_IPC.au3> for an implementation of this

   

• There is both a Local and Global Atom Table. The Local one is local to this Process,   and the Global one is available/accessible to/from all Processes.

   

• Atoms numbered 0 - 49151 (0xBFFF) are not actually part of the Atom Table.   Querying these values will return a string representation of the number as an unsigned integer

     Example: 1234 is translated to "#1234"

   

• Adding atom strings that start with a "#" will return an unsigned integer if the numbers   following "#" are an integer less than 49152 (1 - 49151 [0xBFFF]).

      Examples: "#1" => 1, "#49151" => 49151

   

• Atoms numbered from 49152 - 65535 (from 0xC000 - 0xFFFF) DO reference the Atom Table strings

   

• Maximum Atom string length is 255 characters (not including a null-terminator)

 

Functions:

;  Local:
;    _AtomTableInit()        ; Initializes Local Atom Table. Optional [37 hash buckets allocated by default]
;    _AtomAddLocal()            ; Adds a string to the Local Atom table, returns # identifier [increments reference if already exists]
;    _AtomGetNameLocal()        ; Gets the Local Atom string associated with a numerical identifier
;    _AtomDeleteLocal()        ; Decrements the reference count of Local Atom, deletes when reaches 0
;    _AtomFindLocal()        ; Finds # identifier for a string in the Local Atom table
;    _AtomGetAllLocal()        ; Returns all found Local atoms in an array
; Global:
;    _AtomAddGlobal()        ; Adds a string to the Global Atom table, returns # identifier [increments reference if already exists]
;    _AtomGetNameGlobal()    ; Gets the Global Atom string associated with a numerical identifier
;    _AtomDeleteGlobal()        ; Decrements the reference count of Global Atom, deletes when reaches 0
;    _AtomFindGlobal()        ; Finds # identifier for a string in the Global Atom table
;    _AtomGetAllGlobal()        ; Returns all found Global atoms in an array
; 'Undocumented':
;    _AtomGetGlobalTableUD() ; Using 'undocumented' function calls, gets info on all Global Atoms
;    _AtomGetInfoUD()        ; Returns reference count, pinned status, as well as Atom Name

----------------------------------------------------------------

There are a few 'undocumented' functions used for getting information on the Atom Table included (I can't help myself).

In addition to the core UDF, there's 2 example files:

• AtomTableExample.au3 - This demonstrates various use - adding, deleting, and querying information in the Local and Global atom tables. (Extended info comes from 'undocumented' functions)

   

• AtomExample_IPC.au3 - This demonstrates how the Atom Table could be used in InterProcess Communication. A rather rough sketch, but shows how you could squeeze MAX_PATH pathnames into IPC messages combined with Atom tables.

It's all a bit light on the documentation, but I just wanted to prevent this thing from collecting more dust   Might prove useful to someone!

History::

Update 2014-08-17:

- Added some documentation to all functions

- made the ugly 'AtomTableExample' script into something half-decent.

- IPC script modified to change how messages are reported

- Added array-length return in @extended in 'GetAll' functions

AtomTablesUDF.zip ~prev Downloads: 29

 

Edited August 19, 2014 by Ascend4nt

[jchd]

Something new everyday! Thanks for sharing.

[Ascend4nt]

So I just looked at the script today and thought it was too much of a mess.  I cleaned it up a little so now the examples make a little more sense   See 1st post for updated version

Update 2014-08-17:

- Added some documentation to all functions

- made the ugly 'AtomTableExample' script into something half-decent.

- IPC script modified to change how messages are reported

- Added array-length return in @extended in 'GetAll' functions

[guinness]

Very cool