CMC/CSA: Interfacing with the GroupWise 5 Data Store
Articles and Tips: article
Technical Writer
GroupWare Division
01 Sep 1996
Introduces the Common Messaging Call/Calendar and Scheduling API (CMC/CSA). Also gives an example program.
Introduction
The Common Messaging Call/Calendar and Scheduling API (CMC/CSA) is a functional interface to the GroupWise data store. It has one access point into the GroupWise domain, providing a server-style interface as a client. This API uses the CMC 1.0 and CSA 1.0 extensions to the basic calls to support the GroupWise Universal Mailbox and all message types.
You can use the CMC/CSA to:
Log in
Read messages
Send messages
Obtain user directories
Handle message attachments
Set message priorities
Manage file security
Handle folders
When you are using the CMC/CSA, memory allocation must be done through a cmc_malloc call which contains a size parameter and returns a zeroed memory chunk or NULL. To protect your code from colliding with other heaps in memory, use cmc_free to free memory chunks. A memory chunk may be allocated using the CMC/CSA heap, then attempt to free itself using the application server's heap. To reduce this possibility, clean up the lists after you have completed your tasks. The sample code provided in this article for freeing chunks has been tested and should be followed closely.
The GroupWise message types for sending and receiving are Mail, Appointment, Task, and Note. The CMCNOVL.H, XCMC.H, and XCSA.H files (included with the GroupWise SDK) contain strings which represent the message type syntax. For example, CMC:IPM represents Mail, BLT:APPTrepresents Appointment, BLT:NOTE represents Note, and BLT:PHONErepresents Phone Message.
The GroupWise SDK contains all functions that Novell has created to extend the functionality of the CMC/CSA 1.0 specification document. For information about obtaining CMC/CSA documentation, write to: X.400 API Association, 2141 Landings Drive, Mountain View, CA, 74043.
Portability
All CMC/CSA functions created by Novell are portable to NLM, NT, Ansi C, and OS/2.
Sample CMC/CSA Code
The following code has been written using the CMC/CSA API and has been tested for usability. You may copy this code for your personal use.
Sample 1: Login
This is a login sample. The password and user ID are filled in. The return value contains a Greenwich mean time (GMT) offset, the user's full name, and the number of unread messages.
if ( pUser->Password[0] != 0 && pUser->UserId[0] != 0 )
{
w_memset( &pUser->Extension, 0, MAX_EXTENSION * sizeof(&
CMC_extension ));
pUser->Extension[MAX_EXTENSION -1].extension_flags =
CMC_EXT_LAST_ELEMENT;
/************************************************************/
rett = cmc_logon( NULL, pUser->UserId, pUser->Password, NULL, 0,
CMC_VERSION, 0,
&pUser->session,&
&pUser->Extension[0] );&
/*************************************************************/
switch( rett )
{
case CMC_E_LOGON_FAILURE:
case CMC_E_PASSWORD_REQUIRED:
/* DISPLAY incorrect */
pUser->rtn = RET_CANCEL;
pUser->Trys--;
break;
case CMC_E_FAILURE:
default:
case CMC_E_SERVICE_UNAVAILABLE:
pUser->rtn = RET_OK;
pUser->Trys = -1;
break;
case CMC_SUCCESS:
/* full name is extension 0 item reference, unread items in item data and extension 1 item
reference is the GMT offset Note that the extensions are not freed, but the item references are */
strcpy( pUser->MyName, pUser->Extension[0].item_reference ); pUser->NewItems
= pUser->Extension[0].item_data; cmc_free( pUser->Extension[0].item_reference
);
/* the time zone offset comes in minutes. This work uses seconds.*/
lii = atol( pUser->Extension[1].item_reference);
cmc_free( pUser->Extension[1].item_reference);
pUser->rtn = RET_OK;
goto main3;
}
return;
}
Sample 2: CSA Message Read
This is a sample of a CSA message read from a list. The ent_list is a list of message references. The ref_list is a list of the attributes which will be returned.
a_hand = find_csa( pUser->ent_list, pUser->ItemIndex);
ref_list[0] = CSA_ENTRY_ATTR_ATTENDEE_LIST;
ref_list[1] = CSA_ENTRY_ATTR_DESCRIPTION;
ref_list[2] = CSA_ENTRY_ATTR_END_DATE;
ref_list[3] = CSA_ENTRY_ATTR_SPONSOR;
ref_list[4] = CSA_ENTRY_ATTR_START_DATE;
ref_list[5] = CSA_ENTRY_ATTR_STATUS;
ref_list[6] = CSA_ENTRY_ATTR_SUMMARY;
ref_list[7] = CSA_ENTRY_ATTR_TYPE;
ref_list[8] = CSA_ENTRY_ATTR_PRIORITY;
ref_list[9] = CSA_ENTRY_ATTR_CLASSIFICATION; /* security */
ref_list[10] = CSA_ENTRY_ATTR_DUE_DATE; /* Reply Request Date */
/* The extension is set to null for safekeeping. It will return any extensions to the basic
message, such as recipient TO, CC, BC classification.*/
pUser->Extension[1].item_reference = NULL;
pUser->Extension[1].item_code = 0;
/***************************************************************/
rett = csa_read_entry_attributes(
pUser->session, a_hand, 11, &ref_list[0],&
(CSA_uint32 *) &pUser->num_attrib, &pUser->attrib_list,&
(CSA_extension *) &pUser->Extension[1]);&
if ( rett == CSA_SUCCESS ){ pUser->rtn = RET_OK;
}
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.