Function : Views; Folders

NIFOpenCollection - Access a collection of notes using a view or folder.
----------------------------------------------------------------------------------------------------------

#include <nif.h>

STATUS LNPUBLIC NIFOpenCollection(
DBHANDLE hViewDB,
DBHANDLE hDataDB,
NOTEID ViewNoteID,
WORD OpenFlags,
DHANDLE hUnreadList,
HCOLLECTION far *rethCollection,
NOTEHANDLE far *rethViewNote,
UNID far *retViewUNID,
DHANDLE far *rethCollapsedList,
DHANDLE far *rethSelectedList
);

Description :

This function opens a collection of notes. It yields a collection handle. To access the collection, pass the collection handle as input to NIF functions like NIFReadEntries. Close the collection when finished accessing it using NIFCloseCollection; this will free the memory associated with the collection.

A collection is a representation of a view or folder at one point in time. It consists of a filtered and sorted set of entries, where each entry corresponds to a document in the database or a category in the view or folder. NIFOpenCollection uses the view or folder definition and the state of the database to create or update the collection.

A collection is created the first time the view is opened by indexing all documents in the database that match the view selection criteria for views. Documents in folders are also indexed. Collections are saved in the database file on disk so that opening an existing collection is very fast if the database has been minimally modified. If the on-disk collection is out of date with respect to the notes in the database, generally, NIFOpenCollection will automatically perform a partial search of the database for all notes created or modified since the last time the collection was updated. It updates the collection with entries for the new or modified notes before returning to the caller.

Use NIFReadEntries after opening the collection to get information about the notes in the collection. The collection does not reflect documents created or modified after the collection was opened. Use NIFUpdateCollection to update an open collection. Also use NIFUpdateCollection if the SignalFlag returned by NIFReadEntries indicates that the collection should be updated. In this case, NIFReadEntries will need to be called again to obtain the updated collection information.

NIFOpenCollection can also return other information about the view or folder and the database at the same time it opens the collection. See arguments 5, 7, 8, 9, and 10.

NOTE: The behavior described above is the default behavior for this function. The behavior may be modified by setting one or more of the flags in the 4th parameter.

NOTE: If there are concurrent applications updating the same databases, then the collection may not be automatically updated when it is reopened. This will happen when the views and documents are in separate databases.

NOTE: Only the following configurations are supported by NIFOpenCollection for views: the hDataDB argument references the same database as the hViewDB argument, or the hViewDB argument references a LOCAL database, and the hDataDB argument references a remote database. For folders, the hDataDB argument must reference the same database as the hViewDB argument.


Parameters :

Sample Usage :

/* This code fragment shows how to get a collection of
the notes in a view, given the view's name. */

     if (error = NIFFindView(
                  hDB,
                  szViewName,
                  &ViewID))
          return(error);

      if (error = NIFOpenCollection(
               hDB,
               hDB,  
                ViewID,
               0,  
                NULLHANDLE,  
                &hCollection,
                NULL,  
                NULL,
               NULL,    
                NULL))
        return(error);



See Also :

IDCreateTable
----------------------------------------------------------------------------------------------------------