Outline Add In Programs

Chapter 12-16

Outline Add-In Programs

Introduction

You can add items to a Notes database outline control and configure Notes to call your API program each time the user interacts with one of these outline entries. The API program must be a Windows DLL that provides a outline add-in function. Install your DLL on the Notes workstation and configure Notes to load your DLL when the user starts running the workstation. Notes sends messages to your outline add-in function so that your function can extend the database outline and respond when the user selects your outline entries.

You must specify the name of your outline add-in DLL in the AddInOutlines variable in the notes.ini file that configures the Notes workstation. To list multiple add-in DLL names, separate the names with a comma. For example, to add the DLLs outlineaddin1.dll and outlineaddin2.dll to the Notes workstation, add the following line to notes.ini:

AddInOutlines = OUTLINEADDIN1.DLL, OUTLINEADDIN2.DLL

In this example, the add-in DLLs must reside in a directory in the path. Alternatively, you can specify the full path name of the DLLs in the notes.ini file.

The name of the add-in DLL may begin with the platform specifier character used in the names of other Notes API add-in programs: n under Windows 32-bit. If the DLL name contains a platform specifier character, you may omit the character when specifying the name in the AddInOutlines variable in the notes.ini file.

Technical Description

An add-in DLL must have the following entry point:

wMsg is one of the following messages:

pParam is message-specific data.

The entry point can have any legal function name. You must declare the function in the EXPORTS section of the add-in's module definition (.def) file and assign it an ordinal value of 1.

The add-in module must include addinout.h.

NAOM_INIT

This message is sent after the DLL has been initially loaded.

When the NAOM_INIT message is passed to AddinOutlineProc, pParam is unused, and AddinOutlineProc always returns NAO_NOERROR.

NAOM_QUERY_OUTLINE

This message is sent to the DLL when an outline has been created to determine if NAOM_INIT_OUTLINE should be invoked and the outline extended.

When the NAOM_QUERY_OUTLINE message is passed to AddinOutlineProc, pParam is a pointer to a NAO_OUTLINE_INFO structure.

typedef {
DWORD dwSize; char char DBHANDLE hDb; BOOL bExtendOutline; DWORD dwReserved1; DWORD dwReserved2; } NAO_OUTLINE_INFO;

When the NAOM_QUERY_OUTLINE
If bExtendOutline is set

typedef {
char char DBHANDLE hDb; NOTEHANDLE hNote; NOTELINK nlNoteLink; } NAO_ENTRY_RESOURCE;

typedef {
DWORD dwSize; char DWORD dwID; DWORD dwParentID; DWORD dwRefID; DWORD dwSecRefID; DWORD dwReserved1; DWORD dwReserved2; } NAO_ENTRY_DATA;

typedef {
DWORD dwSize; char DBID DbID; DBHANDLE hDb; DWORD dwReserved1; DWORD dwReserved2; } NAO_IMAGE_DATA;

typedef {
DWORD dwSize; NAO_ENTRY_DATA EntryData; NAO_ENTRY_RESOURCE EntryResource; WORD wEntryResourceType; NAO_IMAGE_DATA ImageData; DWORD dwReserved1; DWORD dwReserved2; } NAO_ENTRY_INFO;

The NAO_ENTRY_DATA structure
When the NAOM_INIT_OUTLINE struct
/ Size of this structure /
szName[DESIGN_FORM_MAX]; / Outline name /
szAlias[DESIGN_FORM_MAX]; / Outline alias /
/ Handle to current Db /
/ Indicates whether or not to extend outline /
/ Reserved /
/ Reserved /
message is passed, AddinOutlineProc always returns NAO_NOERROR.
to TRUE then a subsequent call into the DLL will be made passing in the NAO_INIT_OUTLINE message.
">NAOM_INIT_OUTLINE
the DLL when an applicable outline has been initially created, as in a database open, in order to load the root entries of the extension.
message is passed to AddinOutlineProc, pParam is a pointer to a NAO_ENTRY_INFO structure.
union
szFormula[NAO_LENGTH_FORMULA]; / Formula /
szURL[NAO_LENGTH_URL]; / URL /
/ Database /
/ Note /
/ Link /
struct
/ Size of this structure /
szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
/ Outline entry ID /
/ ID of parent outline entry /
/ Outline reference ID, only used by DLL implementation /
/ Outline reference ID, only used by DLL implementation /
/ Reserved /
/ Reserved /
struct
/ Size of this structure /
szName[DESIGN_NAME_MAX]; / Image name /
/ Replica ID containing szImageName, if not current database /
/ Handle containing szImageName, if not current database and not on workspace /
/ Reserved /
/ Reserved /
struct
/ Size of this structure /
/ NAO_ENTRY_DATA /
/ NAO_ENTRY_RESOURCE /
/ NAO_RESOURCE_XXX /
/ NAO_IMAGE_DATA /
/ Reserved /
/ Reserved /
member dwParentID should be set to 0 for a root entry.
message is passed, AddinOutlineProc returns one of the following values:

The default image if left unspecified is the default database icon.
The replica ID of the database containing the image only needs to be passed in if the image is not in the current database.
The database handle of the database containing the image only needs to be passed in if the database is not currently on the user's workspace. This will add a hidden entry on the workspace. This is necessary if you
plan to make use of remote images from another database. This handle only needs to be passed in on the first usage of a given remote database.

More information on the NAO_RESOURCE_XXX flags is given below.

NAOM_QUERY_OPEN

This message is sent to the DLL when an applicable outline entry has been expanded to determine if NAOM_OPEN should be invoked.

When the NAO_QUERY_OPEN message is passed to AddinOutlineProc, pParam is a pointer to a NAO_SELECT_INFO structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
WORD wLevel; / Outline level, root = 0 /
BOOL bNeedsRefresh; / Indicates outline refresh is needed /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_SELECT_INFO;

When the NAO_QUERY_OPEN message is passed, AddinOutlineProc always returns NAO_NOERROR.
If bNeedsRefresh is set then the call to subsequent call into the DLL will be made passing in the NAOM_OPEN message.

NAOM_OPEN

This message is sent to the DLL when an applicable outline entry has been expanded and the bNeedsRefresh field of the NAO_SELECT_INFO field has been set through the NAOM_QUERY_OPEN message. The corresponding sub-entries are dynamically loaded.

When the NAOM_OPEN message is passed to AddinOutlineProc, pParam is a pointer to a NAO_ENTRY_INFO structure.

typedef union
{
char szFormula[NAO_LENGTH_FORMULA]; / Formula /
char szURL[NAO_LENGTH_URL]; / URL /
DBHANDLE hDb; / Database /
NOTEHANDLE hNote; / Note /
NOTELINK nlNoteLink; / Link /
} NAO_ENTRY_RESOURCE;

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Image name /
DBID DbID; / Replica ID containing szImageName, if not current database /
DBHANDLE hDb; / Handle containing szImageName, if not current database and not on workspace /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_IMAGE_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
NAO_ENTRY_RESOURCE EntryResource; / NAO_ENTRY_RESOURCE /
WORD wEntryResourceType; / NAO_RESOURCE_XXX /
NAO_IMAGE_DATA ImageData; / NAO_IMAGE_DATA /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_INFO;

When the NAOM_OPEN message is passed, AddinOutlineProc returns one of the following values:

The default image if left unspecified is the default database icon.
The replica ID of the database containing the image only needs to be passed in if the image is not in the current database.
The database handle of the database containing the image only needs to be passed in if the database is not currently on the user's workspace. This will add a hidden entry on the workspace. This is necessary if you
plan to make use of remote images from another database. This handle only needs to be passed in on the first usage of a given remote database.

More information on the NAO_RESOURCE_XXX flags is given below.

NAOM_CLOSE

This message is sent to the DLL when an applicable outline entry has been collapsed.

When the NAOM_CLOSE message is passed to AddinOutlineProc, pParam is a pointer to a NAO_SELECT_INFO structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
WORD wLevel; / Outline level, root = 0 /
BOOL bNeedsRefresh; / Indicates outline refresh is needed /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_SELECT_INFO;

When the NAOM_CLOSE message is passed, AddinOutlineProc always returns NAO_NOERROR.

NAOM_SELECT

This message is sent to the DLL when the user has selected one of the add-in outline entries

When the NAOM_SELECT message is passed to AddinOutlineProc, pParam is a pointer to a NAO_SELECT_INFO structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
WORD wLevel; / Outline level, root = 0 /
BOOL bNeedsRefresh; / Indicates outline refresh is needed /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_SELECT_INFO;

When the NAOM_SELECT message is passed, AddinOutlineProc always returns NAO_NOERROR.

The NAOM_SELECT message is passed whenever the user has selected one of the add-in outline entries. If a resource action is associated with the outline entry then NAOM_SELECT will be passed just prior to invoking the defined action.

NAOM_POST_SELECT

This message is sent to the DLL after the user has selected one of the add-in outline entries

When the NAOM_POST_SELECT message is passed to AddinOutlineProc, pParam is a pointer to a NAO_SELECT_INFO structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
WORD wLevel; / Outline level, root = 0 /
BOOL bNeedsRefresh; / Indicates outline refresh is needed /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_SELECT_INFO;

When the NAOM_POST_SELECT message is passed, AddinOutlineProc always returns NAO_NOERROR.

The NAOM_POST_SELECT message is passed whenever after user has selected one of the add-in outline entries that contains a resource link. If the outline entry is a just a simple entry with no resource action associated with it then only the NAOM_SELECT message will be issued.

NAOM_DRAGDROP_DOC

This message is sent to the DLL when documents are dragged and dropped from an add-in folder to another add-in folder, and add-in folder to a notes folder and a notes folder to an add-in folder.

When the NAO_DRAGDROP_DOC message is passed to AddinOutlineProc, pParam is a pointer to a NAO_DRAGDROP structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_NAME_MAX]; / Outline entry name, full title or named element /
DWORD dwID; / Outline entry ID /
DWORD dwParentID; / ID of parent outline entry /
DWORD dwRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwSecRefID; / Outline reference ID, only used by DLL implementation /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_ENTRY_DATA;

typedef struct
{
DWORD dwSize; / Size of this structure /
NAO_ENTRY_DATA EntryData; / NAO_ENTRY_DATA /
WORD wLevel; / Outline level, root = 0 /
BOOL bNeedsRefresh; / Indicates outline refresh is needed /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_SELECT_INFO;

typedef struct
{
DWORD dwSize; / Size of this structure /
BOOL bMove; / TRUE if MOVE, FALSE if COPY /
DWORD dwCount; / Number of documents being dropped /
DBHANDLE hSourceDb; / Source database handle for these notes /
HANDLE hIDTable; / ID table of documents to drop into folder /
DBHANDLE hDestDb; / Destination database handle for these notes /
NAO_SELECT_INFO DestFolderInfo; / NAO_SELECT_INFO of destination folder /
BOOL bNamedFolder; / TRUE if destination folder has a named folder element /
BOOL bActionEntry; / TRUE if destination folder has a action element /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_DRAGDROP_DOC;

When the NAOM_DRAGDROP_DOC message is passed, AddinOutlineProc always returns NAO_NOERROR.

If the destination folder is an add-in folder then the NAOM_DRAGDROP_DOC message will be sent to the outline extension responsible for that folder regardless of the source folder. If the destination folder is a notes folder and the source folder is an add-in folder then the NAOM_DRAGDROP_DOC message will be sent to the outline extension responsible for the source folder. Drag / Drop functionality is not supported between two different outline extensions.

In this context szName will contain the full title of the outline entry or if applicable the named element (folder) which the outline entry is associated.
The hDestDB is a handle to the database where the destination entry is located. The hSourceDB is a handle to the database containing the notes to be drag/dropped.

NAOM_TERM_OUTLINE

This message is sent to the DLL when an applicable outline has been removed, as in a database close.

When the NAOM_TERM_OUTLINE message is passed to AddinOutlineProc, pParam is a pointer to a NAO_OUTLINE_INFO structure.

typedef struct
{
DWORD dwSize; / Size of this structure /
char szName[DESIGN_FORM_MAX]; / Outline name /
char szAlias[DESIGN_FORM_MAX]; / Outline alias /
DBHANDLE hDb; / Handle to current Db /
BOOL bExtendOutline; / Indicates whether or not to extend outline /
DWORD dwReserved1; / Reserved /
DWORD dwReserved2; / Reserved /
} NAO_OUTLINE_INFO;

When the NAOM_TERM_OUTLINE message is passed, AddinOutlineProc always returns NAO_NOERROR.

bExtendOutline is always set to FALSE in the case of NAOM_TERM_OUTLINE.

NAOM_TERM

This message gives the DLL a chance to free any storage that it allocated before Notes frees it.

When NAOM_TERM message is passed to AddinOutlineProc, pParam is unused, and AddinOutlineProc always returns NAO_NOERROR.

Notes Outline Add-in resource values.

NAO_RESOURCE_NONE - No default resource action

NAO_RESOURCE_FORMULA - Resource action is formula

NAO_RESOURCE_URL - Resource action is a URL

NAO_RESOURCE_DB - Resource action is a database handle

NAO_RESOURCE_NOTE - Resource action is a note handle NAO_RESOURCE_NOTELINK - Resource action is a Notes link

Notes Outline Add-in Template

Known Limitations and Usage Restrictions

Outline add-in programs are only supported on Windows 32-bit Notes clients.

Right-Click menu options are not supported.

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