I'm not sure what you're asking for. There are notifiers that let you know when the current document changes. You can get the handle to the current document as well, which is a good way to know which document you're 'currently' talking to. You can't talk to the dictionaries of a document is current, maybe that's what you're asking?
My problem is, when I am working with just one document (#1), everything is fine. I can read/write to the dictionary. When I create the second document, my dictionary read/writes fail. I suspect I am not doing something I need when I respond to the Notifier that says a different document (#2) is selected.
Is the dictionary "global" in nature, or do I need to create a new one for every document I create with my panel?
Is there a document->dictionary association, and if so, what is it.
The sample code with the SDK isn't real clear about documenting how the dictionary works.
It depends on where you're getting the dictionary. There are actually several places to get dictionaries, and you can even create your own (which is sort of necessary, since you can have entries in dictionaries that are themselves dictionaries!). Art objects, layers, they also have dictionaries. Live Effects have them, and a few other special cases have them too (some of the advanced stroke options).
If you're using AIDocumentSuite::GetDictionary() -- as I suspect you are -- then, yes, that's document specific. That means that you can't keep writing out to the same dicitonary if the user switches documents. Getting the document's dictionary is pretty cheap though; if you're hanging on to that handle one simple solution is just get it fresh every time you want to talk to the dictionary. That way you won't get complaints when the current document switches. If you try and talk to objects from a document when another one is 'current', you'll almost always get errors.
That said, if you're doing something that invovles the current document's dictionary and it involves a panel, you'll definitely want to react to the document changed notifier! Our product has several panels, and they interact with dictionaries all the time. Keeping the panels updated when the document changes is one of the important tasks of any panel (usually!). You'll be interested in: kAIDocumentChangedNotifier, kAIDocumentOpenedNotifier & kAIDocumentClosedNotifier.
Also, the sample code isn't a great place for explanations. I'd go to the actual suite headers, which aren't bad for documentation. AIDocument.h has this:
/** Retrieves the recorded dictionary associated with the current document.
Changes in this dictionary and its contents are recorded in the undo history.
Dictionaries are reference counted. You must call \c #AIDictionarySuite::Release()
when you no longer need the reference.
@param dictionary [out] A buffer in which to return a pointer to
the dictionary reference.
@see \c #GetNonRecordedDictionary()
AIAPI AIErr (*GetDictionary) ( struct _AIDictionary** dictionary );