OSID - osid.contact.ContactAdminSession Service Interface Definition

Interface	osid.contact.ContactAdminSession
Implements	`osid.OsidSession`
Implemented By	`osid.contact.batch.ContactBatchAdminSession`
Used By	`osid.contact.ContactManager`
Used By	`osid.contact.ContactProxyManager`
Description	This session creates, updates, and deletes `Contacts`. The data for create and update is provided by the consumer via the form object. `OsidForms` are requested for each create or update and may not be reused. Create and update operations differ in their usage. To create a `Contact`, a `ContactForm` is requested using `getContactFormForCreate()` specifying the desired relationship peers and record `Types` or none if no record `Types` are needed. The returned `ContactForm` will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the `ContactForm` is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each `ContactForm` corresponds to an attempted transaction. For updates, `ContactForms` are requested to the `Contact` `Id` that is to be updated using `getContactFormForUpdate()`. Similarly, the `ContactForm` has metadata about the data that can be updated and it can perform validation before submitting the update. The `ContactForm` can only be used once for a successful update and cannot be reused. The delete operations delete `Addresses`. To unmap a `Contact` from the current `AddressBook`, the `ContactAddressBookAssignmentSession` should be used. These delete operations attempt to remove the `Address` itself thus removing it from all known `ContactForm` catalogs. This session includes an `Id` aliasing mechanism to assign an external `Id` to an internally assigned Id.
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	canCreateContacts
Description	Tests if this user can create contacts. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a `Contact` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
Return	`boolean`		`false` if `Contact` creation is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	canCreateContactWithRecordTypes
Description	Tests if this user can create a single `Contact` using the desired record types. While `ContactManager.getContactRecordTypes()` can be used to examine which records are supported, this method tests which record(s) are required for creating a specific `Contact`. Providing an empty array tests if a `Contact` can be created with no records.
Parameters	`osid.type.Type[]`	`contactRecordTypes`	array of contact record types
Return	`boolean`		`true` if `Contact` creation using the specified record `Types` is supported, `false` otherwise
Errors	NULL_ARGUMENT		`contactRecordTypes` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getContactFormForCreate
Description	Gets the contact form for creating new contacts. A new form should be requested for each create transaction.
Parameters	`osid.id.Id`	`addressId`	the `Id` for the address
	`osid.id.Id`	`referenceId`	the `Id` for the reference
	`osid.type.Type[]`	`contactRecordTypes`	array of contact record types
Return	`osid.contact.ContactForm`		the contact form
Errors	NOT_FOUND		`addressId` is not found
	NULL_ARGUMENT		`addressId, referenceId`, or `contactRecordTypes` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		unable to get form for requested record types
Compliance	`mandatory`		This method must be implemented.
Method	createContact
Description	Creates a new `Contact`.
Parameters	`osid.contact.ContactForm`	`contactForm`	the form for this `Contact`
Return	`osid.contact.Contact`		the new `Contact`
Errors	ILLEGAL_STATE		`contactForm` already used in a create transaction
	INVALID_ARGUMENT		one or more of the form elements is invalid
	NULL_ARGUMENT		`contactForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`contactForm` did not originate from `getContactFormForCreate()`
Compliance	`mandatory`		This method must be implemented.
Method	canUpdateContacts
Description	Tests if this user can update contacts. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a `Contact` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
Return	`boolean`		`false` if `Contact` modification is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getContactFormForUpdate
Description	Gets the contact form for updating an existing contact. A new contact form should be requested for each update transaction.
Parameters	`osid.id.Id`	`contactId`	the `Id` of the `Contact`
Return	`osid.contact.ContactForm`		the contact form
Errors	NOT_FOUND		`contactId` is not found
	NULL_ARGUMENT		`contactId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	updateContact
Description	Updates an existing contact.
Parameters	`osid.contact.ContactForm`	`contactForm`	the form containing the elements to be updated
Errors	ILLEGAL_STATE		`contactForm` already used in an update transaction
	INVALID_ARGUMENT		the form contains an invalid value
	NULL_ARGUMENT		`contactForm` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`contactForm` did not originate from `getContactFormForUpdate()`
Compliance	`mandatory`		This method must be implemented.
Method	canDeleteContacts
Description	Tests if this user can delete contacts. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an `Contact` will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
Return	`boolean`		`false` if `Contact` deletion is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	deleteContact
Description	Deletes a `Contact`.
Parameters	`osid.id.Id`	`contactId`	the `Id` of the `Contact` to remove
Errors	NOT_FOUND		`contactId` not found
	NULL_ARGUMENT		`contactId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canManageContactAliases
Description	Tests if this user can manage `Id` aliases for `Contacts`. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a `PERMISSION_DENIED`. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
Return	`boolean`		`false` if `Contact` aliasing is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	aliasContact
Description	Adds an `Id` to a `Contact` for the purpose of creating compatibility. The primary `Id` of the `Contact` is determined by the provider. The new `Id` performs as an alias to the primary `Id`. If the alias is a pointer to another contact, it is reassigned to the given contact `Id`.
Parameters	`osid.id.Id`	`contactId`	the `Id` of a `Contact`
Parameters	`osid.id.Id`	`aliasId`	the alias `Id`
Errors	ALREADY_EXISTS		`aliasId` is already assigned
	NOT_FOUND		`contactId` not found
	NULL_ARGUMENT		`contactId` or `aliasId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.