NotebookService

Since: BlackBerry 10.0.0

#include <bb/pim/notebook/NotebookService>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The NotebookService class provides CRUD (create/read/update/delete) operations on Notebook objects and their NotebookEntry objects.

NotebookService is domain-level API that abstracts away all persistence details. Clients of this API need only deal with Notebook and NotebookEntry objects; all object-relational mapping is handled behind the scenes. Functions are provided for adding, retrieving, updating, and deleting Notebook objects and NotebookEntry objects, as well as for searching and counting NotebookEntry objects based on criteria specified in a NotebookEntryFilter.

Signals are provided for clients that want to respond to changes in the underlying database, and indicate when a Notebook or NotebookEntry has been added, updated, or deleted.

Example usage:
// Here's how to add a new Notebook to the default Notebook account, and add
// a NotebookEntry to the new Notebook.  Note that service objects are
// potentially expensive to initialize, so you should not create them on a
// per-use basis as is done below.
AccountKey accountKey = AccountService().defaultAccount( Service::Notebook )
                                        .id();
NotebookService service;

Notebook notebook;
notebook.setName( "New Notebook" );

// You should be sure to check the return code from addNotebook() for
// success
service.addNotebook( &notebook, accountKey );

NotebookEntry entry;
entry.setTitle( "New NotebookEntry" );

// A notebook must have been added to the notebook service before its ID
// can be used below
NotebookId notebookId = notebook.id();

// You should be sure to check the return code from addNotebookEntry() for
// success
service.addNotebookEntry( &entry, notebookId );
Permissions:

To use the NotebookService class in your application, you must enable the following permission in your application's bar-descriptor.xml file: access_pimdomain_notebooks.


Overview

Public Types Index

enum RevisionValue

InvalidRevision = ULLONG_MAX

Public Functions Index

NotebookService (QObject *parent=0)
virtual ~NotebookService ()
NotebookServiceResult::TypeaddNotebook (Notebook *newNotebook, bb::pim::account::AccountKey accountKey)
NotebookServiceResult::TypeaddNotebookEntry (NotebookEntry *newNotebookEntry, const NotebookId &parentNotebookId)
QList< Notebook >allowedParentNotebooks (const NotebookEntryId &entryId=NotebookEntryId()) const
NotebookdefaultNotebook () const
NotebookServiceResult::TypedeleteNotebook (const NotebookId &notebookId)
NotebookServiceResult::TypedeleteNotebookEntry (const NotebookEntryId &entryId)
Notebooknotebook (const NotebookId &notebookId) const
QList< NotebookEntry >notebookEntries (const NotebookEntryFilter &filter=NotebookEntryFilter()) const
QList< NotebookEntry >notebookEntries (SourceRevision *revision, const NotebookEntryFilter &filter=NotebookEntryFilter()) const
NotebookEntrynotebookEntry (const NotebookEntryId &entryId) const
intnotebookEntryCount (const NotebookEntryFilter &filter=NotebookEntryFilter()) const
intnotebookEntryCount (SourceRevision *revision, const NotebookEntryFilter &filter=NotebookEntryFilter()) const
QList< NotebookEntryHeader >notebookEntryHeaders (SourceRevision *revision, const NotebookEntryFilter &filter=NotebookEntryFilter()) const
QList< Notebook >notebooks () const
NotebookServiceResult::TypesetNotebookEntryStatus (const NotebookEntryId &entryId, NotebookEntryStatus::Type status) const
NotebookServiceResult::TypeupdateNotebook (const Notebook &updatedNotebook)
NotebookServiceResult::TypeupdateNotebookEntry (const NotebookEntry &updatedNotebookEntry, const NotebookId &parentNotebookId=NotebookId())

Signals Index

voidnotebookEntriesAdded (const QList< bb::pim::notebook::NotebookEntryId > &entryIds)
voidnotebookEntriesChanged (bb::pim::notebook::SourceRevision revision)
voidnotebookEntriesDeleted (const QList< bb::pim::notebook::NotebookEntryId > &entryIds)
voidnotebookEntriesUpdated (const QList< bb::pim::notebook::NotebookEntryId > &entryIds)
voidnotebooksAdded (const QList< bb::pim::notebook::NotebookId > &notebookIds)
voidnotebooksDeleted (const QList< bb::pim::notebook::NotebookId > &notebookIds)
voidnotebooksUpdated (const QList< bb::pim::notebook::NotebookId > &notebookIds)

Public Types

RevisionValue

Predefined SourceRevision value.

Since:

BlackBerry 10.2.0

InvalidRevision = ULLONG_MAX

Specifies an invalid SourceRevision.

Since:

BlackBerry 10.2.0

Public Functions

NotebookService (

Constructs a new NotebookService with the provided parent.

You don't need to provide a parent when you construct a NotebookService object. If you don't provide a parent, the default value is 0.

Parameters
parent

The parent of the NotebookService, or 0 if no parent is provided.

Since:

BlackBerry 10.0.0

virtual~NotebookService ()

Destructor.

Since:

BlackBerry 10.0.0

NotebookServiceResult::Type addNotebook (
  • Notebook *newNotebook,
  • bb::pim::account::AccountKeyaccountKey )

Adds a new Notebook to the provided account in the database.

If the provided Notebook is successfully added to the database, its ID is updated to match the ID assigned to it by the database, and the notebooksAdded() signal is emitted. If the addition fails, then the ID of the Notebook is made invalid (NotebookId::isValid() will return false) and no signal is emitted.

Parameters
newNotebook

The Notebook to be added to the database. If the Notebook is added successfully, the ID of the Notebook is set. Otherwise, the ID of the Notebook is made invalid.

accountKey

The account to which the provided Notebook should be added.

Return:
NotebookServiceResult::Success if the addition succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

NotebookServiceResult::Type addNotebookEntry (

Adds a new NotebookEntry to the database.

The provided NotebookEntry is added to the Notebook that's specified by its parent notebook ID. If the provided NotebookEntry is successfully added, then the NotebookEntryKey portion of its NotebookEntryId is updated to match the key assigned to it by the database, and the notebookEntriesAdded() signal is emitted. If the addition fails, then the NotebookEntryId is made invalid (NotebookEntryId::isValid() will return false) and no signal is emitted.

Parameters
newNotebookEntry

The NotebookEntry to be added to the database.

parentNotebookId

The ID of the Notebook to which the NotebookEntry should be added.

Return:
NotebookServiceResult::Success if the addition succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

QList< Notebook > allowedParentNotebooks (

Retrieves a list of allowed parent Notebook objects for the NotebookEntry with the provided ID.

Each NotebookEntry belongs to (or is parented by) exactly one Notebook at any given time. You can use this function to retrieve a list of allowed parent Notebook objects for a NotebookEntry, both when creating a new NotebookEntry and when moving a NotebookEntry between parent Notebook objects.

You can invoke this function with an invalid NotebookEntryId argument (or omit the argument altogether) to retrieve a list of allowed parent Notebook objects for a new NotebookEntry. However, since a NotebookEntry has an invalid ID before being added to the NotebookService, it is generally not necessary to omit the NotebookEntryId argument. By using this approach, you do not have to invoke this function in different ways when adding a new NotebookEntry and when moving an existing NotebookEntry between parent Notebook objects.

NotebookEntry objects can generally be moved between parent Notebook objects. However, some NotebookEntry objects have restrictions on which Notebook objects they can be parented by. For example, NotebookEntry objects in an ActiveSync Memo Notebook cannot be moved to a non-ActiveSync Memo Notebook, and vice versa. Before moving a NotebookEntry to a different Notebook, you can use this function to retrieve a list of allowed destinations.

Parameters
entryId

The ID of the NotebookEntry whose allowed parent Notebook objects are to be retrieved. If this parameter is invalid or is omitted, then a list of all Notebook objects that allow new NotebookEntry objects is returned.

Return:

A QList of allowed parent Notebook objects for the provided NotebookEntryId, in no particular order.

Since:

BlackBerry 10.0.0

Notebook defaultNotebook ()

Retrieves the default Notebook for the current perimeter.

Each perimeter has a default Notebook that cannot be deleted. Since this Notebook is guaranteed to exist, applications can use it as a "catch all", placing newly created NotebookEntry objects there if the user does not choose a specific Notebook as a destination.

Return:

The default Notebook for the current perimeter.

Since:

BlackBerry 10.0.0

NotebookServiceResult::Type deleteNotebook (

Deletes a Notebook and all of its contained NotebookEntry objects from the database.

If the deletion of the Notebook with the provided ID is successful, then the notebooksDeleted() signal is emitted, as well a single notebookEntriesDeleted() signal for all of its NotebookEntry objects. If the deletion fails, then no signals are emitted.

Note that some Notebook objects cannot be deleted (this can be verified by querying the Notebook::isDeletable() function). Attempting to delete such a Notebook will fail as outlined below.

Parameters
notebookId

The ID of the Notebook to be deleted.

Return:
NotebookServiceResult::Success if the deletion succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

NotebookServiceResult::Type deleteNotebookEntry (

Deletes a NotebookEntry from the database.

If the deletion of the NotebookEntry with the provided ID is successful, then the notebookEntriesDeleted() signal is emitted. If the deletion fails, then no signal is emitted.

Parameters
entryId

The ID of the NotebookEntry to be deleted.

Return:
NotebookServiceResult::Success if the deletion succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

Notebook notebook (

Retrieves the Notebook with the provided ID.

If no Notebook exists with the provided ID, then an invalid Notebook is returned. You should check the Notebook::isValid() function of the returned Notebook to ensure it is valid before using it.

Parameters
notebookId

The ID of the Notebook to be retrieved.

Return:

The Notebook with the provided ID if it exists, or an invalid Notebook otherwise.

Since:

BlackBerry 10.0.0

QList< NotebookEntry > notebookEntries (

Retrieves the NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

The NotebookEntryFilter parameter can be omitted, in which case a filter that accepts all NotebookEntry objects is used. Thus, you can invoke this function with no argument to obtain a list of all available NotebookEntry objects.

Parameters
filter

The NotebookEntryFilter whose criteria must be matched for a NotebookEntry to be included in the returned list. If this parameter is omitted, then all available NotebookEntry objects are returned.

Return:

A QList of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter, sorted as specified by the sort specifier included in the filter.

Since:

BlackBerry 10.0.0

QList< NotebookEntry > notebookEntries (

Retrieves the NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

The NotebookEntryFilter parameter can be omitted, in which case a filter that accepts all NotebookEntry objects is used.

Parameters
revision[out]

The current revision of the database. If null, then no revision will be returned.

filter

The NotebookEntryFilter whose criteria must be matched for a NotebookEntry to be included in the returned list. If this parameter is omitted, then all available NotebookEntry objects are returned.

Return:

A QList of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter, sorted as specified by the sort specifier included in the filter.

Since:

BlackBerry 10.2.0

NotebookEntry notebookEntry (

Retrieves the NotebookEntry with the provided ID.

If no NotebookEntry exists with the provided ID, then an invalid NotebookEntry is returned. You should check the NotebookEntry::isValid() function of the returned NotebookEntry to ensure it is valid before using it.

Parameters
entryId

The ID of the NotebookEntry to be retrieved.

Return:

The NotebookEntry with the provided ID if it exists, or an invalid NotebookEntry otherwise.

Since:

BlackBerry 10.0.0

int notebookEntryCount (

Retrieves the number of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

The NotebookEntryFilter parameter can be omitted, in which case a filter that accepts all NotebookEntry objects is used. Thus, you can invoke this function with no argument to obtain the number of all available NotebookEntry objects.

Parameters
filter

The NotebookEntryFilter whose criteria must be matched for a NotebookEntry to be included in the returned count. If this parameter is omitted, then all available NotebookEntry objects are counted.

Return:

The number of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

Since:

BlackBerry 10.0.0

int notebookEntryCount (

Retrieves the number of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

The NotebookEntryFilter parameter can be omitted, in which case a filter that accepts all NotebookEntry objects is used.

Parameters
revision[out]

The current revision of the database. If null, then no revision will be returned.

filter

The NotebookEntryFilter whose criteria must be matched for a NotebookEntry to be included in the returned count. If this parameter is omitted, then all available NotebookEntry objects are counted.

Return:

The number of NotebookEntry objects that match the criteria set in the provided NotebookEntryFilter.

Since:

BlackBerry 10.2.0

QList< NotebookEntryHeader > notebookEntryHeaders (

Retrieves the NotebookEntryHeader objects that match the criteria set in the provided NotebookEntryFilter.

The NotebookEntryFilter parameter can be omitted, in which case a filter that accepts all NotebookEntry objects is used.

Parameters
revision[out]

The current revision of the database. If null, then no revision will be returned.

filter

The NotebookEntryFilter whose criteria must be matched for a NotebookEntryHeader to be included in the returned list. If this parameter is omitted, then all available NotebookEntry objects are returned.

Return:

A QList of NotebookEntryHeader objects that match the criteria set in the provided NotebookEntryFilter, sorted as specified by the sort specifier included in the filter.

Since:

BlackBerry 10.2.0

QList< Notebook > notebooks ()

Retrieves all Notebook objects in all accessible accounts.

Return:

A QList of Notebook objects, in no particular order.

Since:

BlackBerry 10.0.0

NotebookServiceResult::Type setNotebookEntryStatus (

Sets the status of the NotebookEntry identified by the provided NotebookEntryId.

Parameters
entryId

The NotebookEntryId of the NotebookEntry to set status on.

status

The NotebookEntryStatus to set on the NotebookEntry

Since:

BlackBerry 10.2.0

NotebookServiceResult::Type updateNotebook (

Updates a Notebook in the database.

The contents of the Notebook in the database are replaced with the contents of the provided Notebook, except for those fields that are not user editable or whose new value violates a NotebookConstraint. Such fields are silently ignored during the update. For example, no Notebook can have its type changed by this function. Similarly, a Notebook that has the NotebookConstraint::NameNotEditable constraint cannot have its name changed by this function.

If the update is successful, then the notebooksUpdated() signal is emitted. If the update fails, then no signal is emitted.

Parameters
updatedNotebook

The Notebook to be updated in the database.

Return:
NotebookServiceResult::Success if the update succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

NotebookServiceResult::Type updateNotebookEntry (

Updates and/or moves a NotebookEntry in the database.

The contents of the NotebookEntry in the database are replaced with the contents of the provided NotebookEntry, except for those fields that are not user editable or whose new value violates a NotebookEntryConstraint. Such fields are silently ignored during the update. For example, no NotebookEntry can have its creation date/time changed by this function. Similarly, a NotebookEntry whose parent Notebook has the NotebookEntryConstraint::MustBeActionable constraint cannot have its status set to NotebookEntryStatus::NotActionable with this function.

You can move the provided NotebookEntry to a different parent Notebook by providing the new parent Notebook object's ID as the second argument to this function. If this argument is omitted or is not valid, then the NotebookEntry is not moved. Before moving a NotebookEntry to a different parent Notebook, you should first query allowedParentNotebooks() to ensure the move is allowed. A move to a disallowed or non-existent Notebook will fail.

If the update is successful, then the notebookEntriesUpdated() signal is emitted. If the update fails, then no signal is emitted.

Parameters
updatedNotebookEntry

The NotebookEntry to be updated in the database.

parentNotebookId

The ID of the parent Notebook to which the provided NotebookEntry should be moved. If this parameter is omitted, then the NotebookEntry is not moved.

Return:
NotebookServiceResult::Success if the update succeeded, or one of the following error status codes:
Since:

BlackBerry 10.0.0

Signals

void notebookEntriesAdded (

Emitted when one or more NotebookEntry objects are added to the database.

Parameters
entryIds

The IDs of the NotebookEntry objects that were added to the database.

Since:

BlackBerry 10.0.0

void notebookEntriesChanged (
  • bb::pim::notebook::SourceRevisionrevision)

Emitted when one or more NotebookEntry objects are added to, updated in or deleted from the database.

Parameters
revision

The current SourceRevision of the database.

Since:

BlackBerry 10.2.0

void notebookEntriesDeleted (

Emitted when one or more NotebookEntry objects are deleted from the database.

Parameters
entryIds

The IDs of the NotebookEntry objects that were deleted from the database.

Since:

BlackBerry 10.0.0

void notebookEntriesUpdated (

Emitted when one or more NotebookEntry objects are updated in the database.

Parameters
entryIds

The IDs of the NotebookEntry objects that were updated in the database.

Since:

BlackBerry 10.0.0

void notebooksAdded (

Emitted when one or more Notebook objects are added to the database.

Parameters
notebookIds

The IDs of the Notebook objects that were added to the database.

Since:

BlackBerry 10.0.0

void notebooksDeleted (

Emitted when one or more Notebook objects are deleted from the database.

Parameters
notebookIds

The IDs of the Notebook objects that were deleted from the database.

Since:

BlackBerry 10.0.0

void notebooksUpdated (

Emitted when one or more Notebook objects are updated in the database.

Parameters
notebookIds

The IDs of the Notebook objects that were updated in the database.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus