The GroupWise CMC/CSA Server-Based Interface

x

x

x

cmc_act_on

Compensates for the lack of:

A Universal Mailbox

Different message types

Out Box status tracking

Folders

Syntax

cmc_act_on <extension(s)<

Extensions

CMC_NOV_ACCEPTED_UNACCEPTED

Accepts a message or an autodate group.

item_code In - CMC_NOV_ACCEPTED_UNACCEPTED(firstextension). If you want to accept a group, you must usea second extension with CMC_NOV_STATUS_GROUPas the item_code.

item_data In -CMC_NOV_ACCEPTED

CMC_NOV_ADD_FOLDER

Adds a folder to user, users, or personal groups.

item_code In - CMC_NOV_ADD_FOLDER

item_data In - This field must contain the parent folderindex number.

item_reference In - This field must contain the new folder'sname.

CMC_NOV_COMPLETED

Marks a task as complete.

item_code In - CMC_NOV_COMPLETED,ifthis item is not an autodate item. If thisis an autodate item, and you want all instancestouched, enter STATUS_GROUP in thisfield.

Note: The existence of the CMC_NOV_STATUS_GROUPfieldindicates an autodate item.

CMC_NOV_DELEGATED

Delegates a message to another user or users.

item_code In - CMC_NOV_DELEGATE

item_reference In - A detailed CMC_message of the new information required to delegate. This includes an item_type of CMC_IPM,the new To Recipients, and three extensions (see the following table).

Extension

item_code

item_reference

First extension

CMC_NOV_DELEG_COMMENT

String describingthe delegation.

Second extension

CMC_NOV_DELEG_BY

String describing"delegated by."

Third extension

CMC_NOV_DELEG_TO

String describing"delegated to."

CMC_NOV_DEL_FOLDER

Deletes a folder from a user, users, or personal groups.

item_code In - CMC_NOV_DEL_FOLDER

item_data In - This field must contain the folder index number.

When you call this function, all messages in thefolder are deletedas well. You may want toeither send a warning message to the user,or create a safety function that only deletesempty folders.

CMC_NOV_ATTACH_PUSH

A forwarded GroupWise message encapsulates the original message as a special attachment type. The encapsulated message can then be used to drop down one layer to get the original message attachments as well.

Follow the sample code carefully. You can go as many as eight levels down in the attachment structure. Use CMC_NOV_ATTACH_POPto move up the attachment tree. After a search has been made of unread messages, In Box, Out Box, or folders, cmc_act_onwith CLOSE_BOX must be called to reset the unread message count and get new mail.

item_code In - CMC_NOV_ATTACH_PUSH

item_data In - This field displays a return value of ATTACH_INDEX.

item_reference Out - A new detailed CMC_message.

CMC_NOV_CLOSE_BOX

Searches for an item.

item_code In - CMC_NOV_CLOSE_BOX(first extension)

Return Values The new unread message count appears in the item_data field.

CMC_NOV_FORWARD

Forwards a message that has been read.

item_code In - CMC_NOV_FORWARD

item_type In - CMC_IPM is displayed in a detailed message.

item_reference In - This field contains a new detailed CMC_ message type.

message_reference In - The combined Database Record Number (DRN) andrelative numbers as a string. If the original message is from CSA, the message reference is generated by 0 and the relative offset value in the current selection from the CSA entry list. See free_act_on_ext in the sample code for an example of how to release all the allocated memory.

See also CMC_NOV_REPLY

CMC_NOV_MOVE_FOLDER

Moves messages between folders.

item_code In - CMC_NOV_MOVE_FOLDER

item_data In - This field contains the folder index value of the destination folder. Other folders begin at 0. The index in the root folder is -1. This value is obtained from the folder list explained in the cmc_listsection (see cmc_list).CMC_NOV_REPLY

CMC_NOV_REPLY

Replies to a message that has been read. A reply needs all the message parts of a new message (such as Subject,TEXT_NOTE, and Attachments.)

item_code In - CMC_NOV_REPLY

item_reference In - This field contains the new reply.

Return Values Return values for this function call are different for each extension. See your CMC/CSA documentation for complete information aboutreturn values.

cmc_act_on_delete

Deletes a single or combined autodate entry. Autodates apply toAppointments, Notes, and Tasks.

item_code In - If you delete a group, you must use anextension with CMC_NOV_STATUS_GROUPas the item_code.

Return Values None.

cmc_list

Retrieves a list of unread or selected messages. CMC_LIST_UNREAD_ONLY can be used after a cmc_act_on call to CMC_ACT_ON_EXTENDEDwith the extension of CMC_NOV_CLOSE_BOX.

The return summary references contain the message referencevalues, subject, and other information.

The message reference contains two parts: (1)the first number is the permanent DatabaseRecord Number (DRN) ofthe record in the database;and (2) the second number is the relative offsetof this item in the current selection list.Return both when referencing a message fordetail or other activity.

Extensions

CMC_NOV_FOLDER

Lists all folders. Typically, the application asksfor the folder list only at Login, or when a folder is added ordeleted. The folder list will not contain the root folder. Rememberto free the folder list at Logout.

item_code In - CMC_NOV_ALL_TYPES.Each entry in the extension list has CMC_NOV_FOLDERin this field.

item_type BR>In - BLT:LIST FOLDERS

item_reference Out - A string with syntax: number.foldernameLEVEL levelnumber DRN recordnumber. For example,

0.Applications LEVEL 1 DRN 458. 1.Old Applications LEVEL 2 DRN 1709.2.Conference LEVEL 1 DRN 356.>

This string must be parsed for the folder index valuewhich is the first number before the period. The LEVEL value providesan indication of the tree structure. The DRN is an absolute databaserecord number used for retrieval.

Return Values If the return value is nonzero, the folder list willbe in the summary list's first element message_summary_extensions.

The root folder value is -1. A value of -2 means no folders were found.

Selection Criteria Select In Box, Out Box, and Folder items (excludingunread items). Calendar selections are done through CSA calls. To use CMC_LIST, you must know the message types, mailbox(In Box, Out Box, In Folder, Out Folder), and any keyword forsearching. Two extensions are used to fill in this information(see the following table).

Extension

item_code

Other fields

code

definition

Firstextension

CMC_NOV_MAIL_UNOPENEDAPPT

Messages andUnacceptedAppointments

For In Boxes or Out Boxes with folders,the item_data (in) field should contain thefolder index value.

If you are using keywordsin a search, they are stored in an item_reference(in) field which is allocated in this extension.

CMC_NOV_ALLTYPES

All types ofmessages

CMC_NOV_MAILONLY

No calendarinformation

Secondextension

CMC_NOV_INBOX

InBox itemsonly.

item_type

BLT: FOLDER

Folder searching.

CMM_NOV_OUTBOX

Out Box itemsonly.

BLT: INBOX

In Boxsearchingonly.

BLT: OUTBOX

Out Boxsearchingonly.

cmc_logoff

Logs off the system. This function only requires the current sessionhandle. See also CSA_LOGOFF.

Return Values None

cmc_logon

Logs onto the system.

A user ID and password are required.The user ID must be either:(1)domain.postoffice.userid;(2) postoffice.userid; or (3) userid. It must be unique in the GroupWise domains. Passwordsare case-sensitive and cannot be NULL.

To discourage unauthorized access, users arepermitted three loginattempts on the sameuser ID before a 10-minute response failure timeoccurs. See also CSA_LOGON.

Return Values On return, the first extensioncontains the full name in the item_referencefield,and the number of unread messages in theitem_data field.

The second extension'sitem_referencefield contains the Greenwich mean time (GMT)offset,including daylight saving time (DST),in minutes.

The item_reference field ofboth extensions must be freed.

The session handle that is returned must be used in allsubsequent CMC/CSA calls until the Logoff.

Each post office to which the API will connectmusthave a Universal Naming Code (UNC) pathdefinition.

cmc_look_up

Lists users and personal groups. The sample code uses CMC_LOOK_UPonly when it is building a message, but it can also be used forlisting users or personal groups (see the following table).

Users

CMC_TYPE_INDIVIDUAL

domain.postoffice.userid

CMC_LOOKUP_RESOLVE_IDENTITY(out)

postoffice.userid

userid

first name,last name(wildcards allowed)

CMC_LOOKUP_RESOLVE_PREFIX_SEARCH(out)

Personal Groups

CMC_TYPE_GROUP

CMC_LOOKUP_RESOLVE_IDENTITY(out)

Return Values On user lookups, the return list displays eachuser=sname (first, last) and address(domain.postoffice.userid). Otherextensions which may contain informationare CMC_NOV_DEPARTMENT,CMC_NOV_PHONE,CMC_NOV_TITLE, and CMC_NOV_FAX.

On personal group lookups, the return list displaysonlygroup names. The address does not apply.

The following table provides count indications.

CMC_SUCCESS

1

CMC_E_AMBIGUOUS_RECIPIENT

>1

CMC_E_RECIPIENT_NOT_FOUND

0

cmc_query_configuration

Initializes or terminates the GroupWise datastoreengine. No session handle is used. See also CSA_QUERY_CONFIGURATION.

item_typeIn - Any item type can be used.

Initialize

cmc_read

Reads a message from a selected list.

This function supports the absolute Database Record Number (DRN)value for message retrieval. In the message reference, if thesecond number (the relative offset) is 0, then the first number(the DRN) is used.

If a CMC_NOV_SECURITYextension is found, the default normal security ofCMC_SECURE_NORMALhas likely been replaced by CMC_SECURE_PROPRIETARY,CMC_SECURE_CONFIDENTIAL, CMC_SECURE_SECRET,CMC_SECURE_TOP_SECRET, or CMC_SECURE_FOR_YOUR_EYes_ONLY.

CMC_NOV_PRIORITYcan be _HIGH, _NORMAL, or _LOW.

item_codeIn - The only available extension flag in this fieldis CMC_NOV_TRANSLATE_ATTACH.If you use it, all attachments will try to convert to extendedASCII from the binary file. Otherwise, all attachments are leftas original binary files in clear text. In the sample SAYMAILcall, all of the extensions are used.

Return Values

item_typeOut - The item_type can be CMC IPM(Mail), BLT:NOTE (Note), BLT:APPT(Appointment), or BLT:TASK(Task). Recipients are sorted To, CC, and BCC.

item_codeOut - CMC_NOV_STATUS. Extensions are used for all statuses.

item_dataOut -

CMC_NOV_COMPLETED
CMC_NOV_ACCEPTED
CMC_NOV_UNACCEPTED

The following statuses apply to Out Box status tracking:

CMC_NOV_STATUS_ACCEPTED
CMC_NOV_STATUS_COMPLETED
CMC_NOV_STATUS_DATE
CMC_NOV_STATUS_DECLINED
CMC_NOV_STATUS_DELEGATED
CMC_NOV_STATUS_DELETED
CMC_NOV_STATUS_DELIVERED
CMC_NOV_STATUS_DOWNLOADED
CMC_NOV_STATUS_MESSAGE
CMC_NOV_STATUS_PURGED
CMC_NOV_STATUS_READ
CMC_NOV_STATUS_REPLIED
CMC_NOV_STATUS_RETRACTED
CMC_NOV_STATUS_STARTED
CMC_NOV_STATUS_UNACCEPTED
CMC_NOV_STATUS_UNDELETED
CMC_NOV_STATUS_UNDELIVERABLE

item_referenceOut - The following table provides information aboutthe item_reference field.

CMC_NOV_STATUS_MESSAGE

Provides messagestatuses.

CMC_NOV_LOCATION

Handles Appointmentlocations.

CMC_NOV_BEGIN_SECONDSCMC_NOV_END_SECONDS

These extensionshave a CMC_time structure in this field. In the sample code, the beginning and endingtimes mean different things for a Task oran Appointment.

CMC_NOV_STATUS_USER

Contains therecipient=s name in the item_reference (out)field.

CMC_NOV_STATUS_GROUP

Indicates anautodate item. There are other copies ofthe same Appointment with a different date.

CMC_NOV_PHONE_FROMCMC_NOV_PHONE_OFCMC_NOV_PHONE_AT

Indicate voicemail items.

CMC_NOV_REQUEST_DATE

This extensionhas a CMC_time structure in this field ifa reply is requested.

cmc_send

Sends mail messages.

item_type In - CMC IPM. There can be as many as 99 attachments of any type.

Return Values CMC_SUCCESSCMC_FAIL

csa_add_entry

Adds all calendar message types (Appointments, Tasks, Notes).You must use this function for each attendee or group on the attendee list.

Attributes

CSA_ENTRY_ATTR_TYPE

This must be one of three message types: CSA_TYPE_EVENT, CSA_TYPE_TODO, or CSA_TYPE_MEMO.

CSA_VALUE_STRING

The main message text is an attribute of value CSA_VALUE_STRINGwith type CSA_ENTRY_ATTR_DESCRIPTION. Anyattachments are tied to the extension of this attribute withtype CMC_NOV_HAS_ATTACHMENT.

CSA_ENTRY_ATTR_PRIORITY

If the security is class PUBLIC, PRIVATE, or CONFIDENTIAL, theCSA_CLASSis used. Otherwise, CSA_NOV_CLASS_SECRET, TOP_SECRET, or FOR_YOUR_EYes_ONLY are used toextend the security to meet GroupWise classifications. Thefrom-originator is not needed as it is always the logged-in user.

CSA_ENTRY_ATTR_START_DATE

Used for Appointment and Task.

CSA_ENTRY_ATTR_END_DATE

Used for Appointment and Task. The Task end dateis the due date.

CSA_ENTRY_ATTR_DUE_DATE

Used for the reply request date.

CSA_ENTRY_ATTR_SUMMARY

This is the subject. The location is attached to the CSA_ENTRY_ATTR_SUMMARYas a CMC_NOV_LOCATIONextension.

item_code In - CSA_NOV_CSA_ROLE

item_data In - CSA_ROLE_TO

Return Values On return, the Attendee List contains entrieswith CSA_USER_TYPE_GROUPor_INDIVIDUAL,a status of CSA_STATUS_NEEDS_ACTION, anda full GroupWise address of domain.postoffice.userid.

csa_delete_entry

Deletes autodate entries. This call handles CSA_SCOPE_ONEand CSA_SCOPE_ALL in the delete scope. This entry comes from a handle value on the entry list.

Return Values CSA_SUCCESS

csa_free

Frees memory chunks. All memory allocation must use CMC_MALLOC.

Return Values CSA_SUCCESS

Returns a list of free times.

The date/time ranges are assumed to be the startof the first day andthe end of the last day.

All users in the attendee list are searched by direct userdatabase open, not via OFS messages routed through the MessageServer. If the user'sbox is not accessible, all time is assumed to be available.

Return Values CSA_SUCCESS

Searches for calendar type messages only. You can useone or all of the three type constants as the value. If you want all calendar type messages, add all three types together.

In - List_operators is NULL. Start date and end date attributesare required.

Return Values This is a CMC_message_summary type on the extensionof the list entries call.

csa_logon

Logs onto the system.

In - A user ID and password are required. The user ID must be domain.postoffice.userid or postoffice.userid or userid. It must be unique in the GroupWise domains. Passwordsare case sensitive and cannot be NULL. To discourage unauthorizedaccess, users are permitted three login attempts on the same userID before a 10-minute response failure time occurs. See also CMC_LOGON.

Return Values On return, the first extension contains the full name in the item_referencefield, and the number of unread messages in the item_data field.

The second extension's item_reference field contains the Greenwich mean time (GMT) offset, including daylight saving time (DST), in minutes.

The item_reference field of both extensions must be freed.

The session handle that is returned must be usedin all subsequent CMC/CSA calls until the Logoff.

Each post office to which the API will connect musthave a Universal Naming Code (UNC) path definition.

Logs off the system. This function only requires the currentsession handle. See also CMC_LOGOFF.

Return Values None.

Initializes or terminates the GroupWise datastore engine.No session handle is used. See also CMC_QUERY_CONFIGURATION.

item_type Any item type can be used.

>Reads calendar attributes. All memory allocation must useCMC_MALLOC.

Attributes

CSA_CAL_ATTR_TIME_ZONE

Returns a time zone offset.

CSA_CAL_ATTR_VERSION

Returns version 1.0.

Return Values CSA_SUCCESS

Reads messages and message attributes. In your call, includeany attributes that you want returned.

Attributes

CSA_ENTRY_ATTR_ATTENDEE_LIST

Each entry in the attendee list has: (1) To, CC,andBCC as an extension of CMC_NOV_CSA_ROLEinthe item_code field; and (2) CMC_ROLE_TOinthe item_data field. The items are sortedby To, then by CC.

CSA_ENTRY_ATTR_DESCRIPTION

This contains the message text, and the attachments of theCMC_attachment format are on the extension. If the attachments are to be translated,CMC_NOV_TRANSLATE_ATTACHmust be in the item_code field.

CSA_ENTRY_ATTR_END_DATE

A date type. See also CSA_ENTRY_ATTR_START_DATE andCSA_ENTRY_ATTR_DUE_DATE.

CSA_ENTRY_ATTR_SPONSOR

This is the user who sent the message.

CSA_ENTRY_ATTR_START_DATE

A date type. See also CSA_ENTRY_ATTR_END_DATE andCSA_ENTRY_ATTR_DUE_DATE.

CSA_ENTRY_ATTR_STATUS

Contains the message status (for example, Opened, Accepted,Completed).

CSA_ENTRY_ATTR_SUMMARY

Contains the message subject. In the extension, CMC_NOV_LOCATION is in the item_code field and the location string is in the item_reference field.

CSA_ENTRY_ATTR_TYPE

Must be set to one of three message types: CSA_TYPE_TASK, CSA_TYPE_MEMO, CSA_TYPE_EVENT.

CSA_ENTRY_ATTR_PRIORITY

The message's send priority (for example, High, Normal,Low).

CSA_ENTRY_ATTR_CLASSIFICATION

The message's security classification (for example, Public, TopSecret, For Your Eyes Only).

CSA_ENTRY_ATTR_DUE_DATE

The date type for the reply requested date. See also CSA_ENTRY_ATTR_START_DATEand CSA_ENTRY_ATTR_END_DATE.

Marks messages as completed, accepted, or delegated. ThisAPI supports CSA_SCOPE_ONEand CSA_SCOPE_ALL.

Attributes

CSA_ENTRY_ATTR_STATUS

Can have values of CSA_STATUS_ACCEPTED, CSA_STATUS_COMPLETED, and CSA_STATUS_DELEGATED.

If the status is CSA_STATUS_DELEGATED,the following two fields apply:

CSA_ENTRY_ATTR_DESCRIPTION

Used to attach the Delegate From, Delegate By, and DelegateTo strings as extensions (see sample code). If you do not include these delegation extensions, defaults are used.

CSA_ENTRY_ATTENDEE_LIST

A list of the delegation recipients.

Return Values CSA_SUCCESSCSA_FAIL