File Name
Syntax
CleanUpMessageContent(REF msg:STRING);
Parameters
msg: new message content
Returns
Nothing
Side Effects
None
Description
This function scans a message for "bad characters" and replaces each occurrence with a blank character.
Dialog Forms Called
None
File Name
Syntax
DumpStructEvent(REF emailData:EmailDataRec);
Parameters
Returns
Nothing
Side Effects
None
Description
This routine provides bare bones event handling for the Dump Structure window.
Dialog Forms Called
None
File Name
Syntax
EMailDeleteCurrentMessage(REF emailData:EMailDataRec);
Parameters
emailData: conceptual "Email login handle"
Returns
1 = success
0 = failure: no container open or message to delete
-n = Read failure status: see KML MAIL error codes
Side Effects
None
Description
This function deletes the message read via the last call to EMailReadNextNewMessage. Failure to Delete the message leaves the message in the account "In box" folder, marked as "read".
Dialog Forms Called
None
File Name
Syntax
EMailGetReadMessageCount(REF emailData:EMailDataRec, REF readMsgCount:INTEGER);
Parameters
emailData: conceptual "Email login handle"
readMsgCount:
Returns
1 = success
EMAIL_ERR_NOT_LOGGED_IN = failure -- not logged in
ERR_NONFATAL = Read failure: may be able to continue
ERR_FATAL = Read failure: cannot continue
emailData.emailStatus => holds the last KML Mail status code
Side Effects
None
Description
This function samples the account inbox and determines the the number of "read" messages. Note: This call is expensive.
Dialog Forms Called
None
File Name
Syntax
EMailGetUnreadMessageCount(REF emailData:EMailDataRec, REF unreadMsgCount:INTEGER);
Parameters
emailData: conceptual "Email login handle"
unreadMsgCount:
Returns
1 = success
EMAIL_ERR_NOT_LOGGED_IN = failure -- not logged in
ERR_NONFATAL = Read failure: may be able to continue
ERR_FATAL = Read failure: cannot continue
emailData.emailStatus => holds the last KML Mail status code
Side Effects
None
Description
This function samples the unread message queue and returns the count. Note: If you intend to read a message right after determining the count, it is highly recommended that you simply call ReadNextNewMessage directly and skip calling this routine.
Dialog Forms Called
None
File Name
Syntax
EMailInitData(REF emailData:EMailDataRec);
Parameters
emailData: "Email handle", identifies mail session
Returns
1 = success
Side Effects
None
Description
This function initializes an email data record for general use.
Dialog Forms Called
None
File Name
Syntax
EMailLogin( REF emailData:EMailDataRec, REF emailSystemType:INTEGER, REF accountName:STRING, REF accountPassword:STRING, REF emailPostOffice:STRING, REF emailServer:STRING, REF emailContainer:STRING, VAL parentWindow:WINDOW, VAL tries:INTEGER );
Parameters
emailData: conceptual "Email login handle"
emailSystemName: which major EMAIL system to be used
accountName: name of account
accountPassword: password of account
emailPostOffice: this will be either 1) a path to
the post office database files for
cc:Mail, or 2) the Server Name for SMTP/POP.
emailContainer: the full path to the file that is to
serve as the email "container" (SMTP/POP only).
parentWindow: if prompting the user, use this handle
tries: max login attempt count (if parentWindow exists)
Returns
1 = success
0 = user cancel or login failure
ERR_NONFATAL = OpenSession failure: may be able to continue
ERR_FATAL = OpenSession failure: cannot continue
emailData.loginData.loginStatus => holds the KML Mail login status code
Side Effects
None
Description
This function logs a new session with the mail system. If the parentWindow parameter is supplied, it is assumed that the user is to be prompted interactively, using the Name, Password and PO as default values. If the parentWindow is Unknown, then it is assumed that the values passed in are complete and will be used directly to open a mail session.
Dialog Forms Called
None
File Name
Syntax
EMailLoginEventHandler(REF loginData: EMailLoginDataRec);
Parameters
loginData: instance data for this dialog type
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine provides event handling for the EMail Login dialog box. It accomplishes three things: 1) Makes sure the proper fields are en/disabled as the email system choice is made. 2) It will also try to be smart about setting focus if the account is available and the password is not. 3) It will attempt to open the mail session and return the status of that attempt.
Dialog Forms Called
None
File Name
Syntax
EMailLogout(REF emailData:EMailDataRec);
Parameters
emailData: "Email handle", identifies mail session
Returns
1 = success
Side Effects
None
Description
The emailData structure supplied is wiped clean.
Dialog Forms Called
None
File Name
Syntax
EMailOpenContainer( REF emailData:EMailDataRec, VAL attemptFailover:BOOLEAN );
Parameters
emailData: standard structure 'handle'
attemptfailOver: flag indicating whether failover attempts
should be made if the KML function fails.
Returns
1 = success
Side Effects
None
Description
This function "covers" the equivalent KML MailOpenMessageContainer function. It provides all the standard error detection and correction required of every function in THIS module which attempts to open a container.
Dialog Forms Called
None
File Name
Syntax
EMailPrepareOutgoingMessage( REF msgBody:STRING );
Parameters
msgBody: the message text to be prepared
Returns
1 = success
Side Effects
None
Description
This function prepares an outgoing mail message body which came in via Email. The oddities of cc:Mail indenting, line breaking and wrapping need to be put into a form that cc:Mail will accept gracefully on "redelivery".
Dialog Forms Called
None
File Name
Syntax
EMailReadNextNewMessage(REF emailData:EMailDataRec, REF msgSubject:STRING, REF msgBody:STRING, REF msgAttachmentList:LIST OF STRING, REF msgFrom:STRING, REF remainingMsgCount:INTEGER, VAL attemptFailover:BOOLEAN );
Parameters
emailData: conceptual "Email login handle"
msgSubject: new message "Subject" text
msgBody: new message content
msgAttachmentList: list of attachment filenames
remainingMsgCount: remaining messages
attemptfailOver: flag indicating whether failover attempts
should be made if the KML function fails.
Returns
1 = success
2 = Bad message in system: found a good message anyway
0 = no more messages
EMAIL_ERR_NOT_LOGGED_IN = failure -- not logged in
ERR_NONFATAL = Read failure: may be able to continue
ERR_FATAL = Read failure: cannot continue
emailData.emailStatus => holds the last KML Mail status code
Side Effects
None
Description
This function reads the next new mail message for the account referenced in this emailData handle. If there is a new (unread) message, this routine reads it in and marks it has having been read. The message content is deposited in the obvious REF arguments passed in. The system also reports the total amount of remaining unread messages. Note that this routine will retain the list of messages of a scan between calls. It will only rescan the EMail Inbox if the items in the previous scan have all been processed. Thus, the "remainingMsgCount" will only be accurate if a new scan is performed. Note also that this approach means you MUST NOT ALLOW MULTIPLE READERS OF THIS EMAIL ACCOUNT. This approach is being implemented for performance reasons; the cost of rescanning a deeply populated Inbox is enormous. When you have completed your operations with the new mail message, you should call EMailDeleteCurrentMessage before. calling this routine again. Note that any message read by this routine is "marked as read". This is so that subsequent calls to this routine will not read the same message a second time.
Dialog Forms Called
None
File Name
Syntax
EMailScanUnreadMessages( REF emailData:EMailDataRec, VAL attemptFailover:BOOLEAN );
Parameters
emailData: standard structure 'handle'
attemptfailOver: flag indicating whether failover attempts
should be made if the KML function fails.
Returns
1 = success
Side Effects
None
Description
This function "covers" the equivalent KML MailScanMessages function. It provides all the standard error detection and correction required of every function in THIS module which attempts to scan for messages.
Dialog Forms Called
None
File Name
Syntax
EMailSendMessage(REF emailData:EMailDataRec, VAL msgSubject:STRING, VAL msgBody:STRING, VAL destinationAccounts:LIST OF STRING, VAL attachmentMsg:STRING );
Parameters
emailData: conceptual "Email login handle"
msgSubject: new message "Subject" text
msgBody: new message content
destinationAccounts: accounts to receive this message
attachmentMsg: if msgBody is to be an attachment,
use this text as the message body.
Returns
1 = success
EMAIL_ERR_NOT_LOGGED_IN = Bad session ID, not logged in.
EMAIL_ERR_CANT_OPEN_MSG_FILE = Unable to open a file for message body
EMAIL_ERR_BAD_DESTINATION = Bad destination (unknown)
ERR_NONFATAL = Send failure: may be able to continue
ERR_FATAL = Send failure: cannot continue
emailData.emailStatus => holds the last KML Mail status code
Side Effects
None
Description
This function sends a message to a list of destinations. The caller must call EMailLogin before calling this routine. If the destination argument is unknown, then this routine functions as a straight EMailReply: it uses whatever email address is located in the emailData record as the destination.
Dialog Forms Called
None
File Name
Syntax
EMailShutDown;
Parameters
None
Returns
1 = success
< 1 = Email error codes for MailTerminate
Side Effects
None
Description
You should call this as your app shuts down. It terminates all KML Mail communication.
Dialog Forms Called
None
File Name
Syntax
EMailStartup(VAL emailProtocol:INTEGER);
Parameters
emailProtocol: VIM or MAPI protocol to be used
Returns
1 = success
0 = This protocol request does not agree with previous call
< 1 = Email error codes for MailInitialize
Side Effects
None
Description
You should call this as your app starts up. It should only be called once.
Dialog Forms Called
None
File Name
Syntax
EMailSystemTypeNum(VAL emailSystemName:STRING);
Parameters
emailSystemName: the email system as a string
Returns
one of the EMAIL_TYPE_xxx values. (Default is CCMAIL.)
Currently known types:
EMAIL_TYPE_CCMAIL
EMAIL_TYPE_GRPWISE
EMAIL_TYPE_EXCHANGE
EMAIL_TYPE_MSMAIL
EMAIL_TYPE_NOTESMAIL
EMAIL_TYPE_SMTPPOP
Side Effects
None
Description
This routine translates the string representing an Email System name into an integer. In other words, translate the STR_EMAIL_TYPE_xxx to its equivalent EMAIL_TYPE_xxx.
Dialog Forms Called
None
File Name
Syntax
EmailTest;
Parameters
None
Returns
Nothing
Side Effects
None
Description
This function creates a dialog box of type Xxxx. Before calling this function, you should ALWAYS call XxxxGetData on your first argument, and override any necessary values. Failure to call GetData will result in the 'normal' defaults not being applied.
Dialog Forms Called
None
File Name
Syntax
EMailTestEventHandler( REF emailTestData:EmailTestRec);
Parameters
emailTestData: the instance data for this dialog type
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine provides event handling for the EMailTest dialog. Note: Since the last statement of this event handler is to transfer the instance record info to the module-wide static data, be sure to avoid using EXIT unless you wish to prevent the record update.
Dialog Forms Called
None
File Name
Syntax
HandleDeleteBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleDumpBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW);
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleGetreadBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleGetUnreadBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleListSelect(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleLoginBtn( REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleLogoutBtn(VAL listBoxName:STRING, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleReadBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
HandleSendBtn(REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW, VAL passNoDestination:BOOLEAN);
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box
passNoDestination: ignore the input fields in GUI
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
PerformAction( REF emailTestData:EmailTestRec, VAL dlgHandle:WINDOW, VAL controlName:STRING, VAL controlID:INTEGER );
Parameters
emailTestData: the instance data for this window
dlgHandle: window handle of dialog box.
controlName: name of the control selected.
controlID: number id of the control selected.
$EventParm(3,T): old value of the object.
$EventParm(4,T): new value of the object.
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the EMail test dialog box.
Dialog Forms Called
None
File Name
Syntax
PerformSelectAction(VAL controlName:STRING, VAL controlID:INTEGER);
Parameters
controlName: name of the control selected.
controlID: number id of the control selected.
$EventParm(3,T): old value of the object.
$EventParm(4,T): new value of the object.
Returns
1 = success
0 = failure
Side Effects
None
Description
This routine performs actions for controls in the email login dialog.
Dialog Forms Called
None
File Name
Syntax
StatusOfKMLMailCall(REF emailData:EMailDataRec, VAL mailStatus:INTEGER );
Parameters
status: KML MAIL read return status code
Returns
ERR_NONFATAL = Read failure: may be able to continue
ERR_FATAL = Read failure: cannot continue
1 = successful call
Side Effects
None
Description
This function attempts to interpret the KML MAIL error code as "recoverable" or "non-recoverable". Any codes it does not recognize are assumed to be non-recoverable.
Dialog Forms Called
None
File Name
Syntax
UpdateLoginDialog( VAL mailSysType:INTEGER );
Parameters
mailSysType: The mail system type
Returns
Nothing
Side Effects
None
Description
This routine enables/disables and labels the appropriate fields for the selected mail system.
Dialog Forms Called
None
File Name
Syntax
UpdateLoginFields(VAL dlgHandle:WINDOW, VAL emailData:EMailDataRec, VAL emailSystemType:INTEGER, VAL accountName:STRING, VAL accountPassword:STRING, VAL emailPostOffice:STRING, VAL emailServer:STRING, VAL emailContainer:STRING );
Parameters
Returns
1
Side Effects
None
Description
This function updates the individual login data fields if the field contents have changed.
Dialog Forms Called
None
File Name
Syntax
WriteMsgLns(VAL str1:STRING, VAL str2:STRING);
Parameters
str: output string
Returns
Nothing
Side Effects
None
Description
This function writes a message line out to the status Message field in the test dialog interface.
Dialog Forms Called
None