Parnassus Plugins Common API
Introduction
Several Parnassus plugins provide a publicly accessible API, in order that third-party plugins can interoperate: access their data, invoke specific functionality, etc.
While each plugin specifies its own API, they rely on a common core set of interfaces:
- Enumerable types
- Read-only list
- Multicast events (or list of event sinks)
Types, methods names, etc are prefixed ‘PnAPI’.
Unit PnPluginAPICommon
Enumerable types
1 2 3 4 5 6 7 8 9 10 11 12 | IPnAPIEnumerator<T> = interface [‘{95916880-151B-47FA-AEC3-2D640BCB82AE}’] function GetCurrent: T; function MoveNext: Boolean; procedure Reset; property Current: T read GetCurrent; end; IPnAPIEnumerable<T> = interface [‘{3CB240AD-FAA3-49D3-BBC0-2B14228F97D8}’] function GetEnumerator: IPnEnumerator<T>; end; |
Read-only list
1 2 3 4 5 6 7 | IPnAPIReadOnlyList<T> = interface(IPnEnumerable<T>) [‘{195978C7-83AA-45FB-B2CC-6CF00BDD8308}’] function GetItem(Index: Integer): T; function GetCount : Integer; property Items[Index: Integer]: T read GetItem; default; property Count : Integer read GetCount; end; |
It is enumerable using for..in syntax, and can otherwise have its elements accessed through the default property Items. There are 0..Count-1 elements in the list.
Multicast events
Many plugins or parts of a plugin can expose events, and those events often need to support multiple event handlers – in other words, rather than having On* event handlers where only a single event handler can be set, a list of event handlers is required. In addition, events are often logically related: if there is an event for a bookmark (say) being added, there is also one for it being removed.
The Parnassus API design is that instead of implementing individual event handlers, to implement an interface specifying an event sink for a defined family of events. That interface – the event sink object – is registered by adding it to the list of event sinks.
1 2 3 4 5 6 | IPnAPIMulticastInterfaceList<T : IUnknown> = interface [‘{77B67572-2400-4AF3-80F3-3DEC8491EFF6}’] procedure Add(const Item : T); procedure AddAtStart(const Item : T); procedure Remove(const Item : T); end; |
A multicast interface list is a list of interfaces of a specific type. One example is IPnAPIBookmarkEvents. Items can be added or removed. Each addition should be matched by a removal.
Usually you only want to add or remove your event sink, but occasionally you want to ensure you get events before other event handlers. To do so, call AddAtStart. If multiple sinks are added via AddAtStart, the order of which is the very first is undefined. All items added via AddAtStart will be called before items added via Add.
There is no provision for preventing other event handlers also being notified of an event after your handler has received the notification. There is also no support for enumeration or accessing individual elements, since a consumer of the interface should only ever add or remove items it knows about.
It is essential that you call Remove for every Add. Not doing so will result in access violations on IDE shutdown or when the plugin is unloaded. If you get an access violation on IDE or plugin shutdown, this is the most likely cause.