OSID - osid.contact.ContactNotificationSession Service Interface Definition

Interface	osid.contact.ContactNotificationSession
Implements	`osid.OsidSession`
Used By	`osid.contact.ContactManager`
Used By	`osid.contact.ContactProxyManager`
Description	This session defines methods to receive notifications on adds/changes to `Contacts`. This session is intended for consumers needing to synchronize their state with this service without the use of polling. Notifications are cancelled when this session is closed.
Method	getAddressBookId
Description	Gets the `AddressBook` `Id` associated with this session.
Return	`osid.id.Id`		the `AddressBook Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getAddressBook
Description	Gets the `AddressBook` associated with this session.
Return	`osid.contact.AddressBook`		the address book
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canRegisterForContactNotifications
Description	Tests if this user can register for `Contact` notifications. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer notification operations.
Return	`boolean`		`false` if notification methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useFederatedAddressBookView
Description	Federates the view for methods in this session. A federated view will include contacts in address books which are children of this address book in the address book hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedAddressBookView
Description	Isolates the view for methods in this session. An isolated view restricts retrievals to this address book only.
Compliance	`mandatory`		This method is must be implemented.
Method	reliableContactNotifications
Description	Reliable notifications are desired. In reliable mode, notifications are to be acknowledged using `acknowledgeContactNotification()`.
Compliance	`mandatory`		This method is must be implemented.
Method	unreliableContactNotifications
Description	Unreliable notifications are desired. In unreliable mode, notifications do not need to be acknowledged.
Compliance	`mandatory`		This method is must be implemented.
Method	acknowledgeContactNotification
Description	Acknowledge a contact notification.
Parameters	`osid.id.Id`	`notificationId`	the `Id` of the notification
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForNewContacts
Description	Register for notifications of new contacts. `ContactReceiver.newContacts()` is invoked when a new `Contact` is created.
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForNewContactsByGenusType
Description	Register for notifications of new contacts for the given genus `Type`. `ContactReceiver.newContacts()` is invoked when a new `Contact` is created.
Parameters	`osid.type.Type`	`contactGenusType`	the contact genus type to monitor
Errors	NULL_ARGUMENT		`contactGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForNewContactsForReference
Description	Register for notifications of new contacts for the given reference `Id`. `ContactReceiver.newContacts()` is invoked when a new `Contact` is created.
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference to monitor
Errors	NULL_ARGUMENT		`referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForNewContactsForAddress
Description	Register for notifications of new contacts for the given reference `Id`. `ContactReceiver.newContacts()` is invoked when a new `Contact` is created.
Parameters	`osid.id.Id`	`addressId`	the `Id` of the address to monitor
Errors	NULL_ARGUMENT		`addressId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForChangedContacts
Description	Registers for notification of updated contacts. `ContactReceiver.changedContacts()` is invoked when a contact is changed.
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForChangedContactsByGenusType
Description	Register for notifications of changed contacts for the given contact genus `Type`. `ContactReceiver.changedContacts()` is invoked when a `Contact` for the genus type is changed.
Parameters	`osid.type.Type`	`contactGenusType`	the contact genus type to monitor
Errors	NULL_ARGUMENT		`contactGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForChangedContactsForReference
Description	Register for notifications of changed contacts for the given reference `Id`. `ContactReceiver.changedContacts()` is invoked when a `Contact` for the reference is changed.
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference to monitor
Errors	NULL_ARGUMENT		`referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForChangedContactsForAddress
Description	Register for notifications of changed contacts for the given address `Id`. `ContactReceiver.changedContacts()` is invoked when a `Contact` for the address is changed.
Parameters	`osid.id.Id`	`addressId`	the `Id` of the address to monitor
Errors	NULL_ARGUMENT		`addressId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForChangedContact
Description	Registers for notification of an updated contact. `ContactReceiver.changedContact()` is invoked when the specified contact is changed.
Parameters	`osid.id.Id`	`contactId`	the `Id` of the `Contact` to monitor
Errors	NULL_ARGUMENT		`contactId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForDeletedContacts
Description	Registers for notification of deleted contacts. `ContactReceiver.deletedContacts()` is invoked when a contact is deleted.
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForDeletedContactsByGenusType
Description	Register for notifications of deleted contacts for the given contact genus `Type`. `ContactReceiver.deletedContacts()` is invoked when a `Contact` for the genus type is deleted.
Parameters	`osid.type.Type`	`contactGenusType`	the contact genus type to monitor
Errors	NULL_ARGUMENT		`contactGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForDeletedContactsForReference
Description	Register for notifications of deleted contacts for the given reference `Id`. `ContactReceiver.deletedContacts()` is invoked when a `Contact` for the reference is deleted.
Parameters	`osid.id.Id`	`referenceId`	the `Id` of the reference to monitor
Errors	NULL_ARGUMENT		`referenceId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForDeletedContactsForAddress
Description	Register for notifications of deleted contacts for the given address `Id`. `ContactReceiver.deletedContacts()` is invoked when a `Contact` for the address is deleted.
Parameters	`osid.id.Id`	`addressId`	the `Id` of the address to monitor
Errors	NULL_ARGUMENT		`addressId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	registerForDeletedContact
Description	Registers for notification of a deleted contact. `ContactReceiver.deletedContacts()` is invoked when the specified contact is deleted.
Parameters	`osid.id.Id`	`contactId`	the `Id` of the `Contact` to monitor
Errors	NULL_ARGUMENT		`contactId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.