Thrift module: NoteStore

ModuleServicesData typesConstants
NoteStoreNoteStore
AdImpressions
AdParameters
NoteCollectionCounts
NoteEmailParameters
NoteFilter
NoteList
NoteVersionId
SyncChunk
SyncState

Data structures

Struct: SyncState

FieldTypeRequiredDefault value
currentTimeTypes.Timestampyes
fullSyncBeforeTypes.Timestampyes
updateCounti32yes
uploadedi64no

This structure encapsulates the information about the state of the user's account for the purpose of "state based" synchronization.
currentTime
The server's current date and time.

fullSyncBefore
The cutoff date and time for client caches to be updated via incremental synchronization. Any clients that were last synched with the server before this date/time must do a full resync of all objects. This cutoff point will change over time as archival data is deleted or special circumstances on the service require resynchronization.

updateCount
Indicates the total number of transactions that have been committed within the account. This reflects (for example) the number of discrete additions or modifications that have been made to the data in this account (tags, notes, resources, etc.). This number is the "high water mark" for Update Sequence Numbers (USN) within the account.

uploaded
The total number of bytes that have been uploaded to this account in the current monthly period. This can be compared against Accounting.uploadLimit (from the UserStore) to determine how close the user is to their monthly upload limit.

Struct: SyncChunk

FieldTypeRequiredDefault value
currentTimeTypes.Timestampyes
chunkHighUSNi32no
updateCounti32yes
noteslist<Types.Note>no
notebookslist<Types.Notebook>no
tagslist<Types.Tag>no
searcheslist<Types.SavedSearch>no
resourceslist<Types.Resource>no
expungedNoteslist<Types.Guid>no
expungedNotebookslist<Types.Guid>no
expungedTagslist<Types.Guid>no
expungedSearcheslist<Types.Guid>no

This structure is given out by the NoteStore when a client asks to receive the current state of an account. The client asks for the server's state one chunk at a time in order to allow clients to retrieve the state of a large account without needing to transfer the entire account in a single message.

The server always gives SyncChunks using an ascending series of Update Sequence Numbers (USNs).

currentTime
The server's current date and time.

chunkHighUSN
The highest USN for any of the data objects represented in this sync chunk. If there are no objects in the chunk, this will not be set.

updateCount
The total number of updates that have been performed in the service for this account. This is equal to the highest USN within the account at the point that this SyncChunk was generated. If updateCount and chunkHighUSN are identical, that means that this is the last chunk in the account ... there is no more recent information.

notes
If present, this is a list of non-expunged notes that have a USN in this chunk. This will include notes that are "deleted" but not expunged (i.e. in the trash). The notes will include their list of tags and resources, but the resource content and recognition data will not be supplied.

notebooks
If present, this is a list of non-expunged notebooks that have a USN in this chunk. This will include notebooks that are "deleted" but not expunged (i.e. in the trash).

tags
If present, this is a list of the non-expunged tags that have a USN in this chunk.

searches
If present, this is a list of non-expunged searches that have a USN in this chunk.

resources
If present, this is a list of the non-expunged resources that have a USN in this chunk. This will include the metadata for each resource, but not its binary contents or recognition data, which must be retrieved separately.

expungedNotes
If present, the GUIDs of all of the notes that were permanently expunged in this chunk.

expungedNotebooks
If present, the GUIDs of all of the notebooks that were permanently expunged in this chunk. When a notebook is expunged, this implies that all of its child notes (and their resources) were also expunged.

expungedTags
If present, the GUIDs of all of the tags that were permanently expunged in this chunk.

expungedSearches
If present, the GUIDs of all of the saved searches that were permanently expunged in this chunk.

Struct: NoteFilter

FieldTypeRequiredDefault value
orderi32no
ascendingboolno
wordsstringno
notebookGuidTypes.Guidno
tagGuidslist<Types.Guid>no
timeZonestringno
inactiveboolno

A list of criteria that are used to indicate which notes are desired from the account. This is used in queries to the NoteStore to determine which notes should be retrieved.

order
The NoteSortOrder value indicating what criterion should be used to sort the results of the filter.

ascending
If true, the results will be ascending in the requested sort order. If false, the results will be descending.

words
The string query containing keywords to match, if present.

notebookGuid
If present, the Guid of the notebook that must contain the notes.

tagGuids
If present, the list of tags (by GUID) that must be present on the notes.

timeZone
The zone ID for the user, which will be used to interpret any dates or times in the queries that do not include their desired zone information. For example, if a query requests notes created "yesterday", this will be evaluated from the provided time zone, if provided. The format must be encoded as a standard zone ID such as "America/Los_Angeles".

inactive
If true, then only notes that are not active (i.e. notes in the Trash) will be returned. Otherwise, only active notes will be returned. There is no way to find both active and inactive notes in a single query.

Struct: NoteList

FieldTypeRequiredDefault value
startIndexi32yes
totalNotesi32yes
noteslist<Types.Note>yes
stoppedWordslist<string>no
searchedWordslist<string>no

A small structure for returning a list of notes out of a larger set.

startIndex
The starting index within the overall set of notes. This is also the number of notes that are "before" this list in the set.

totalNotes
The number of notes in the larger set. This can be used to calculate how many notes are "after" this note in the set. (I.e. remaining = totalNotes - (startIndex + notes.length) )

notes
The list of notes from this range. The Notes will include all metadata (attributes, resources, etc.), but will not include the ENML content of the note or the binary contents of any resources.

stoppedWords
If the NoteList was produced using a text based search query that included words that are not indexed or searched by the service, this will include a list of those ignored words.

searchedWords
If the NoteList was produced using a text based search query that included viable search words or quoted expressions, this will include a list of those words. Any stopped words will not be included in this list.

Struct: NoteCollectionCounts

FieldTypeRequiredDefault value
notebookCountsmap<Types.Guid, i32>no
tagCountsmap<Types.Guid, i32>no
trashCounti32no

A data structure representing the number of notes for each notebook and tag with a non-zero set of applicable notes.

notebookCounts
A mapping from the Notebook GUID to the number of notes (from some selection) that are in the corresponding notebook.

tagCounts
A mapping from the Tag GUID to the number of notes (from some selection) that have the corresponding tag.

trashCount
If this is set, then this is the number of notes that are in the trash. If this is not set, then the number of notes in the trash hasn't been reported. (I.e. if there are no notes in the trash, this will be set to 0.)

Struct: AdImpressions

FieldTypeRequiredDefault value
adIdi32yes
impressionCounti32yes
impressionTimei32yes

Information for tracking the display of a particular ad by a client.

adId
The identifier for this ad, from a previous Ad.id given to the client

impressionCount
The number of times this ad was displayed since the last successful ad retrieval. The client should only report times the ad was selected when the client was visible.

impressionTime
The number of seconds that the client displayed the advertisement since the last successful ad retrieval. This corresponds to the seconds that the client application was visible.

Struct: AdParameters

FieldTypeRequiredDefault value
clientLanguagestringno
impressionslist<AdImpressions>no
supportHtmlboolno
clientPropertiesmap<string, string>no

Parameters that will be given by a client to the service when it requests a set of advertisements to display. If any of these values are omitted, the service will use default values.

clientLanguage
The ISO 639-1 language code for the primary language for the client. If omitted, English will be assumed ('en').

impressions
A list of the impression counts and total display time for the ads that were displayed in the last day.

supportHtml
If true, the client requesting the ads supports ads specified via general HTML (with rich media, Javascript, etc.).

clientProperties
If provided, this may contain a set of key/value pairs that identify the characteristics of a particular client that may be used to help determine appropriate ads for that client. These tuples may be used either to reduce or increase the likelihood that each ad will be returned.

Struct: NoteEmailParameters

FieldTypeRequiredDefault value
guidstringno
noteTypes.Noteno
toAddresseslist<string>no
ccAddresseslist<string>no
subjectstringno
messagestringno

Parameters that must be given to the NoteStore emailNote call. These allow the caller to specify the note to send, the recipient addresses, etc.

guid
If set, this must be the GUID of a note within the user's account that should be retrieved from the service and sent as email. If not set, the 'note' field must be provided instead.

note
If the 'guid' field is not set, this field must be provided, including the full contents of the note note (and all of its Resources) to send. This can be used for a Note that as not been created in the service, for example by a local client with local notes.

toAddresses
If provided, this should contain a list of the SMTP email addresses that should be included in the "To:" line of the email. Callers must specify at least one "to" or "cc" email address.

ccAddresses
If provided, this should contain a list of the SMTP email addresses that should be included in the "Cc:" line of the email. Callers must specify at least one "to" or "cc" email address.

subject
If provided, this should contain the subject line of the email that will be sent. If not provided, the title of the note will be used as the subject of the email.

message
If provided, this is additional personal text that should be included into the email as a message from the owner to the recipient(s).

Struct: NoteVersionId

FieldTypeRequiredDefault value
updateSequenceNumi32yes
updatedTypes.Timestampyes
serviceUpdatedTypes.Timestampyes

Identfying information about previous versions of a note that are backed up within Evernote's servers. Used in the return value of the listNoteVersions call.

updateSequenceNum
The update sequence number for the Note when it last had this content. This serves to uniquely identify each version of the note, since USN values are unique within an account for each update.
updated
The 'updated' time that was set on the Note when it had this version of the content. This is the user-modifiable modification time on the note, so it's not reliable for guaranteeing the order of various versions. (E.g. if someone modifies the note, then changes this time manually into the past and then updates the note again.)
serviceUpdated
A timestamp that holds the date and time when the Note that had this version of the content was saved or synchronized on the service. This may be different than the 'updated' time visible on the note in a client, which is a user-editable field that is (therefore) not reliable for determining the order of changes.


Services

Service: NoteStore

Service: NoteStore

The NoteStore service is used by EDAM clients to exchange information about the collection of notes in an account. This is primarily used for synchronization, but could also be used by a "thin" client without a full local cache.

All functions take an "authenticationToken" parameter, which is the value returned by the UserStore which permits access to the account. This parameter is mandatory for all functions.

Calls which require an authenticationToken may throw an EDAMUserException for the following reasons:


Function: NoteStore.getSyncState

SyncState getSyncState(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Asks the NoteStore to provide information about the status of the user account corresponding to the provided authentication token.

Function: NoteStore.getSyncChunk

SyncChunk getSyncChunk(string authenticationToken,
                       i32 afterUSN,
                       i32 maxEntries,
                       bool fullSyncOnly)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Asks the NoteStore to provide the state of the account in order of last modification. This request retrieves one block of the server's state so that a client can make several small requests against a large account rather than getting the entire state in one big message.

@param afterUSN The client can pass this value to ask only for objects that have been updated after a certain point. This allows the client to receive updates after its last checkpoint rather than doing a full synchronization on every pass. The default value of "0" indicates that the client wants to get objects from the start of the account.

@param maxEntries The maximum number of modified objects that should be returned in the result SyncChunk. This can be used to limit the size of each individual message to be friendly for network transfer.

@param fullSyncOnly If true, then the client only wants initial data for a full sync. In this case, the service will not return any expunged objects, and will not return any Resources, since these are also provided in their corresponding Notes.

@throws EDAMUserException


Function: NoteStore.listNotebooks

list<Types.Notebook> listNotebooks(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Returns a list of all of the notebooks in the account.

Function: NoteStore.getNotebook

Types.Notebook getNotebook(string authenticationToken,
                           Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of the notebook with the provided GUID. The notebook may be active or deleted (but not expunged).

@param guid The GUID of the notebook to be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getDefaultNotebook

Types.Notebook getDefaultNotebook(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Returns the notebook that should be used to store new notes in the user's account when no other notebooks are specified.

Function: NoteStore.createNotebook

Types.Notebook createNotebook(string authenticationToken,
                              Types.Notebook notebook)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Asks the service to make a notebook with the provided name.

@param notebook The desired fields for the notebook must be provided on this object. The name of the notebook must be set, and either the 'active' or 'defaultNotebook' fields may be set by the client at creation. If a notebook exists in the account with the same name (via case-insensitive compare), this will throw an EDAMUserException.

@return The newly created Notebook. The server-side GUID will be saved in this object's 'guid' field.

@throws EDAMUserException


Function: NoteStore.updateNotebook

i32 updateNotebook(string authenticationToken,
                   Types.Notebook notebook)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Submits notebook changes to the service. The provided data must include the notebook's guid field for identification.

@param notebook The notebook object containing the requested changes.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeNotebook

i32 expungeNotebook(string authenticationToken,
                    Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Permanently removes the notebook from the user's account. After this action, the notebook is no longer available for undeletion, etc. If the notebook contains any Notes, they will be moved to the current default notebook and moved into the trash (i.e. Note.active=false).

@param guid The GUID of the notebook to delete.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException


Function: NoteStore.listTags

list<Types.Tag> listTags(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Returns a list of the tags in the account. Evernote does not support the undeletion of tags, so this will only include active tags.

Function: NoteStore.listTagsByNotebook

list<Types.Tag> listTagsByNotebook(string authenticationToken,
                                   Types.Guid notebookGuid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns a list of the tags that are applied to at least one note within the provided notebook. If the notebook is public, the authenticationToken may be ignored.

@param notebookGuid the GUID of the notebook to use to find tags

@throws EDAMNotFoundException


Function: NoteStore.getTag

Types.Tag getTag(string authenticationToken,
                 Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of the Tag with the provided GUID.

@param guid The GUID of the tag to be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.createTag

Types.Tag createTag(string authenticationToken,
                    Types.Tag tag)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Asks the service to make a tag with a set of information.

@param tag The desired list of fields for the tag are specified in this object. The caller must specify the tag name, and may provide the parentGUID.

@return The newly created Tag. The server-side GUID will be saved in this object.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.updateTag

i32 updateTag(string authenticationToken,
              Types.Tag tag)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Submits tag changes to the service. The provided data must include the tag's guid field for identification. The service will apply updates to the following tag fields: name, parentGuid

@param tag The tag object containing the requested changes.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.untagAll

void untagAll(string authenticationToken,
              Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Removes the provided tag from every note that is currently tagged with this tag. If this operation is successful, the tag will still be in the account, but it will not be tagged on any notes.

This function is not indended for use by full synchronizing clients, since it does not provide enough result information to the client to reconcile the local state without performing a follow-up sync from the service. This is intended for "thin clients" that need to efficiently support this as a UI operation.

@param guid The GUID of the tag to remove from all notes.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeTag

i32 expungeTag(string authenticationToken,
               Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Permanently deletes the tag with the provided GUID, if present.

@param guid The GUID of the tag to delete.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.listSearches

list<Types.SavedSearch> listSearches(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Returns a list of the searches in the account. Evernote does not support the undeletion of searches, so this will only include active searches.

Function: NoteStore.getSearch

Types.SavedSearch getSearch(string authenticationToken,
                            Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of the search with the provided GUID.

@param guid The GUID of the search to be retrieved.

@throws EDAMUserException


Function: NoteStore.createSearch

Types.SavedSearch createSearch(string authenticationToken,
                               Types.SavedSearch search)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Asks the service to make a saved search with a set of information.

@param search The desired list of fields for the search are specified in this object. The caller must specify the name, query, and format of the search.

@return The newly created SavedSearch. The server-side GUID will be saved in this object.

@throws EDAMUserException


Function: NoteStore.updateSearch

i32 updateSearch(string authenticationToken,
                 Types.SavedSearch search)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Submits search changes to the service. The provided data must include the search's guid field for identification. The service will apply updates to the following search fields: name, query, and format

@param search The search object containing the requested changes.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeSearch

i32 expungeSearch(string authenticationToken,
                  Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Permanently deletes the search with the provided GUID, if present.

@param guid The GUID of the search to delete.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.findNotes

NoteList findNotes(string authenticationToken,
                   NoteFilter filter,
                   i32 offset,
                   i32 maxNotes)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Used to find a set of the notes from a user's account based on various criteria specified via a NoteFilter object. The Notes (and any embedded Resources) will have empty Data bodies for contents, resource data, and resource recognition fields. These values must be retrieved individually.

@param authenticationToken Must be a valid token for the user's account unless the NoteFilter 'notebookGuid' is the GUID of a public notebook.

@param filter The list of criteria that will constrain the notes to be returned.

@param offset The numeric index of the first note to show within the sorted results. The numbering scheme starts with "0". This can be used for pagination.

@param maxNotes The most notes to return in this query. The service will either return this many notes or the end of the notebook, whichever is shorter.

@return The list of notes that match the criteria.

@throws EDAMUserException

Function: NoteStore.findNoteCounts

NoteCollectionCounts findNoteCounts(string authenticationToken,
                                    NoteFilter filter,
                                    bool withTrash)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
This function is used to determine how many notes are found for each notebook and tag in the user's account, given a current set of filter parameters that determine the current selection. This function will return a structure that gives the note count for each notebook and tag that has at least one note under the requested filter. Any notebook or tag that has zero notes in the filtered set will not be listed in the reply to this function (so they can be assumed to be 0).

@param authenticationToken Must be a valid token for the user's account unless the NoteFilter 'notebookGuid' is the GUID of a public notebook.

@param filter The note selection filter that is currently being applied. The note counts are to be calculated with this filter applied to the total set of notes in the user's account.

@param withTrash If true, then the NoteCollectionCounts.trashCount will be calculated and supplied in the reply. Otherwise, the trash value will be omitted.

@throws EDAMUserException

Function: NoteStore.getNote

Types.Note getNote(string authenticationToken,
                   Types.Guid guid,
                   bool withContent,
                   bool withResourcesData,
                   bool withResourcesRecognition,
                   bool withResourcesAlternateData)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of the note in the service with the provided GUID. The ENML contents of the note will only be provided if the 'withContent' parameter is true. The service will include the meta-data for each resource in the note, but the binary contents of the resources and their recognition data will be omitted. If the Note is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the note to be retrieved.

@param withContent If true, the note will include the ENML contents of its 'content' field.

@param withResourcesData If true, any Resource elements in this Note will include the binary contents of their 'data' field's body.

@param withResourcesRecognition If true, any Resource elements will include the binary contents of the 'recognition' field's body if recognition data is present.

@param withResourcesAlternateData If true, any Resource elements in this Note will include the binary contents of their 'alternateData' fields' body, if an alternate form is present.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getNoteContent

string getNoteContent(string authenticationToken,
                      Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns XHTML contents of the note with the provided GUID. If the Note is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the note to be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getNoteSearchText

string getNoteSearchText(string authenticationToken,
                         Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns a block of the extracted plain text contents of the note with the provided GUID. This text can be indexed for search purposes by a light client that doesn't have capabilities to extract all of the searchable text content from the note and its resources.

If the Note is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the note to be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getNoteTagNames

list<string> getNoteTagNames(string authenticationToken,
                             Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns a list of the names of the tags for the note with the provided guid. This can be used with authentication to get the tags for a user's own note, or can be used without valid authentication to retrieve the names of the tags for a note in a public notebook.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.createNote

Types.Note createNote(string authenticationToken,
                      Types.Note note)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Asks the service to make a note with the provided set of information.

@param note A Note object containing the desired fields to be populated on the service.

@return The newly created Note from the service. The server-side GUIDs for the Note and any Resources will be saved in this object.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.updateNote

Types.Note updateNote(string authenticationToken,
                      Types.Note note)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Submit a set of changes to a note to the service. The provided data must include the note's guid field for identification.

@param note A Note object containing the desired fields to be populated on the service.

@return The metadata (no contents) for the Note on the server after the update

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.deleteNote

i32 deleteNote(string authenticationToken,
               Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Moves the note into the trash. The note may still be undeleted, unless it is expunged. This is equivalent to calling udpateNote() after setting Note.active = false

@param guid The GUID of the note to delete.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeNote

i32 expungeNote(string authenticationToken,
                Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Permanently removes the Note, and all of its Resources, from the service.

@param guid The GUID of the note to delete.

@return The Update Sequence Number for this change within the account.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeNotes

i32 expungeNotes(string authenticationToken,
                 list<Types.Guid> noteGuids)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Permanently removes a list of Notes, and all of their Resources, from the service. This should be invoked with a small number of Note GUIDs (e.g. 100 or less) on each call. To expunge a larger number of notes, call this method multiple times. This should also be used to reduce the number of Notes in a notebook before calling expungeNotebook() or in the trash before calling expungeInactiveNotes(), since these calls may be prohibitively slow if there are more than a few hundred notes. If an exception is thrown for any of the GUIDs, then none of the notes will be deleted. I.e. this call can be treated as an atomic transaction.

@param noteGuids The list of GUIDs for the Notes to remove.

@return The account's updateCount at the end of this operation

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.expungeInactiveNotes

i32 expungeInactiveNotes(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Permanently removes all of the Notes that are currently marked as inactive. This is equivalent to "emptying the trash", and these Notes will be gone permanently.

This operation may be relatively slow if the account contains a large number of inactive Notes.

@return The number of notes that were expunged.

Function: NoteStore.copyNote

Types.Note copyNote(string authenticationToken,
                    Types.Guid noteGuid,
                    Types.Guid toNotebookGuid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Performs a deep copy of the Note with the provided GUID 'noteGuid' into the Notebook with the provided GUID 'toNotebookGuid'. The caller must be the owner of both the Note and the Notebook. This creates a new Note in the destination Notebook with new content and Resources that match all of the content and Resources from the original Note, but with new GUID identifiers. The original Note is not modified by this operation. The copied note is considered as an "upload" for the purpose of upload transfer limit calculation, so its size is added to the upload count for the owner.

@param noteGuid The GUID of the Note to copy.

@param toNotebookGuid The GUID of the Notebook that should receive the new Note.

@return The metadata for the new Note that was created. This will include the new GUID for this Note (and any copied Resources), but will not include the content body or the binary bodies of any Resources.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.listNoteVersions

list<NoteVersionId> listNoteVersions(string authenticationToken,
                                     Types.Guid noteGuid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns a list of the prior versions of a particular note that are saved within the service. These prior versions are stored to provide a recovery from unintentional removal of content from a note. The identifiers that are returned by this call can be used with getNoteVersion to retrieve the previous note.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getNoteVersion

Types.Note getNoteVersion(string authenticationToken,
                          Types.Guid noteGuid,
                          i32 updateSequenceNum,
                          bool withResourcesData,
                          bool withResourcesRecognition,
                          bool withResourcesAlternateData)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
This can be used to retrieve a previous version of a Note after it has been updated within the service. The caller must identify the note (via its guid) and the version (via the updateSequenceNumber of that version). to find a listing of the stored version USNs for a note, call listNoteVersions. This call is only available for notes in Premium accounts. (I.e. access to past versions of Notes is a Premium-only feature.)

@param guid The GUID of the note to be retrieved.

@param updateSequenceNum The USN of the version of the note that is being retrieved

@param withResourcesData If true, any Resource elements in this Note will include the binary contents of their 'data' field's body.

@param withResourcesRecognition If true, any Resource elements will include the binary contents of the 'recognition' field's body if recognition data is present.

@param withResourcesAlternateData If true, any Resource elements in this Note will include the binary contents of their 'alternateData' fields' body, if an alternate form is present.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResource

Types.Resource getResource(string authenticationToken,
                           Types.Guid guid,
                           bool withData,
                           bool withRecognition,
                           bool withAttributes,
                           bool withAlternateData)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of the resource in the service with the provided GUID. If the Resource is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the resource to be retrieved.

@param withData If true, the Resource will include the binary contents of the 'data' field's body.

@param withRecognition If true, the Resource will include the binary contents of the 'recognition' field's body if recognition data is present.

@param withAttributes If true, the Resource will include the attributes

@param withAlternateData If true, the Resource will include the binary contents of the 'alternateData' field's body, if an alternate form is present.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.updateResource

i32 updateResource(string authenticationToken,
                   Types.Resource resource)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Submit a set of changes to a resource to the service. This can be used to update the meta-data about the resource, but cannot be used to change the binary contents of the resource (including the length and hash). These cannot be changed directly without creating a new resource and removing the old one via updateNote.

@param resource A Resource object containing the desired fields to be populated on the service. The service will attempt to update the resource with the following fields from the client:

@return The Update Sequence Number of the resource after the changes have been applied.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResourceData

string getResourceData(string authenticationToken,
                       Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns binary data of the resource with the provided GUID. For example, if this were an image resource, this would contain the raw bits of the image. If the Resource is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the resource to be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResourceByHash

Types.Resource getResourceByHash(string authenticationToken,
                                 Types.Guid noteGuid,
                                 string contentHash,
                                 bool withData,
                                 bool withRecognition,
                                 bool withAlternateData)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the current state of a resource, referenced by containing note GUID and resource content hash.

@param noteGuid The GUID of the note that holds the resource to be retrieved.

@param contentHash The MD5 checksum of the resource within that note.

@param withData If true, the Resource will include the binary contents of the 'data' field's body.

@param withRecognition If true, the Resource will include the binary contents of the 'recognition' field's body. @param withAlternateData If true, the Resource will include the binary contents of the 'alternateData' field's body, if an alternate form is present.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResourceRecognition

string getResourceRecognition(string authenticationToken,
                              Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the binary contents of the recognition index for the resource with the provided GUID. If the caller asks about a resource that has no recognition data, this will throw EDAMNotFoundException. If the Resource is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the resource whose recognition data should be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResourceAlternateData

string getResourceAlternateData(string authenticationToken,
                                Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
If the Resource with the provided GUID has an alternate data representation (indicated via the Resource.alternateData field), then this request can be used to retrieve the binary contents of that alternate data file. If the caller asks about a resource that has no alternate data form, this will throw EDAMNotFoundException.

@param guid The GUID of the resource whose recognition data should be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getResourceAttributes

Types.ResourceAttributes getResourceAttributes(string authenticationToken,
                                               Types.Guid guid)
    throws Errors.EDAMUserException, Errors.EDAMSystemException, Errors.EDAMNotFoundException
Returns the set of attributes for the Resource with the provided GUID. If the Resource is found in a public notebook, the authenticationToken will be ignored (so it could be an empty string).

@param guid The GUID of the resource whose attributes should be retrieved.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.getAccountSize

i64 getAccountSize(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
@deprecated - This function is deprecated, and should no longer be used. This will always return a value of '0'.

Function: NoteStore.getAds

list<Types.Ad> getAds(string authenticationToken,
                      AdParameters adParameters)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
Clients should make this call once per day to receive a bundle of ads that will be displayed for the subsequent 24 hour period.

@param adParameters A set of parameters that help the service determine which ads to return.

Function: NoteStore.getRandomAd

Types.Ad getRandomAd(string authenticationToken,
                     AdParameters adParameters)
    throws Errors.EDAMUserException, Errors.EDAMSystemException
A thin client should make this call to retrieve a single random ad for immediate display.

@param adParameters A set of parameters to help the service determine which ad to return. The 'impression' field should either be absent (if no ads have been displayed previously), or else it should contain the identifier for the most recently-displayed ad so that the service can give a different ad.

Function: NoteStore.getPublicNotebook

Types.Notebook getPublicNotebook(Types.UserID userId,
                                 string publicUri)
    throws Errors.EDAMSystemException, Errors.EDAMNotFoundException
Looks for a user account with the provided userId on this NoteStore shard and determines whether that account contains a public notebook with the given URI. If the account is not found, or no public notebook exists with this URI, this will throw an EDAMNotFoundException, otherwise this will return the information for that Notebook.

@throws EDAMNotFoundException


Function: NoteStore.createSharedNotebook

Types.SharedNotebook createSharedNotebook(string authenticationToken,
                                          Types.SharedNotebook sharedNotebook)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Used to construct a shared notebook object. The constructed notebook will contain a "share key" which serve as a unique identifer and access token for a user to access the notebook of the shared notebook owner.

@param sharedNotebook An shared notebook object populated with the email address of the share recipient, the notebook guid and the access permissions. All other attributes of the shared object are ignored. @return The fully populated SharedNotebook object including the server assigned share id and shareKey which can both the used to uniquely identify the SharedNotebook.

@throws EDAMUserException

@throws EDAMNotFoundException

Function: NoteStore.listSharedNotebooks

list<Types.SharedNotebook> listSharedNotebooks(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Lists the collection of shared notebooks for all notebooks in the users account.

@return The list of all SharedNotebooks for the user

Function: NoteStore.expungeSharedNotebooks

i32 expungeSharedNotebooks(string authenticationToken,
                           list<i64> sharedNotebookIds)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Expunges the SharedNotebooks in the user's account using the SharedNotebook.id as the identifier. @param sharedNotebookIds - a list of ShardNotebook.id longs identifying the objects to delete permanently. @return The account's update sequence number.

Function: NoteStore.createLinkedNotebook

Types.LinkedNotebook createLinkedNotebook(string authenticationToken,
                                          Types.LinkedNotebook linkedNotebook)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Asks the service to make a linked notebook with the provided name, username of the owner and identifiers provided. A linked notebook can be either a link to a public notebook or to a private shared notebook.

@param linkedNotebook The desired fields for the linked notebook must be provided on this object. The name of the linked notebook must be set. Either a username uri or a shard id and share key must be provided otherwise a EDAMUserException is thrown.

@return The newly created LinkedNotebook. The server-side id will be saved in this object's 'id' field.

@throws EDAMUserException


Function: NoteStore.updateLinkedNotebook

Types.LinkedNotebook updateLinkedNotebook(string authenticationToken,
                                          Types.LinkedNotebook linkedNotebook)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
@param linkedNotebook Updates the name of a linked notebook.

@throws EDAMUserException


Function: NoteStore.listLinkedNotebooks

list<Types.LinkedNotebook> listLinkedNotebooks(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Returns a list of linked notebooks

Function: NoteStore.expungeLinkedNotebook

i32 expungeLinkedNotebook(string authenticationToken,
                          i64 linkedNotebookId)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Permanently expunges the linked notebook from the account.

@param linkedNotebookId The LinkedNotebook.id field of the LinkedNotebook to permanently remove from the account.

Function: NoteStore.authenticateToSharedNotebook

UserStore.AuthenticationResult authenticateToSharedNotebook(string shareKey,
                                                            string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Asks the service to produce an authentication token that can be used to access the contents of a shared notebook from someone else's account. This authenticationToken can be used with the various other NoteStore calls to find and retrieve notes, and if the permissions in the shared notebook are sufficient, to make changes to the contents of the notebook.

@param shareKey The 'shareKey' identifier from the SharedNotebook that was granted to some recipient. This string internally encodes the notebook identifier and a security signature.

@param authenticationToken If a non-empty string is provided, this is the full user-based authentication token that identifies the user who is currently logged in and trying to access the shared notebook. This may be required if the notebook was created with 'requireLogin'. If this string is empty, the service will attempt to authenticate to the shared notebook without any logged in user.

@throws EDAMSystemException

@throws EDAMNotFoundException

@throws EDAMUserException


Function: NoteStore.getSharedNotebookByAuth

Types.SharedNotebook getSharedNotebookByAuth(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
This function is used to retrieve extended information about a shared notebook by a guest who has already authenticated to access that notebook. This requires an 'authenticationToken' parameter which should be the resut of a call to authenticateToSharedNotebook(...). I.e. this is the token that gives access to the particular shared notebook in someone else's account -- it's not the authenticationToken for the owner of the notebook itself.

@param authenticationToken Should be the authentication token retrieved from the reply of authenticateToSharedNotebook(), proving access to a particular shared notebook.

@throws EDAMUserException

@throws EDAMNotFoundException


Function: NoteStore.emailNote

void emailNote(string authenticationToken,
               NoteEmailParameters parameters)
    throws Errors.EDAMUserException, Errors.EDAMNotFoundException, Errors.EDAMSystemException
Attempts to send a single note to one or more email recipients.

@param authenticationToken The note will be sent as the user logged in via this token, using that user's registered email address. If the authenticated user doesn't have permission to read that note, the emailing will fail.

@param parameters The note must be specified either by GUID (in which case it will be sent using the existing data in the service), or else the full Note must be passed to this call. This also specifies the additional email fields that will be used in the email.

@throws EDAMUserException

@throws EDAMNotFoundException