Routines for ema_mail.kb


CleanUpMessageContent

File Name

ema_mail.kb

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


DumpStructEvent

File Name

ema_mail.kb

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


EMailDeleteCurrentMessage

File Name

ema_mail.kb

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


EMailGetReadMessageCount

File Name

ema_mail.kb

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


EMailGetUnreadMessageCount

File Name

ema_mail.kb

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


EMailInitData

File Name

ema_mail.kb

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


EMailLogin

File Name

ema_mail.kb

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


EMailLoginEventHandler

File Name

ema_mail.kb

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


EMailLogout

File Name

ema_mail.kb

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


EMailOpenContainer

File Name

ema_mail.kb

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


EMailPrepareOutgoingMessage

File Name

ema_mail.kb

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


EMailReadNextNewMessage

File Name

ema_mail.kb

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


EMailScanUnreadMessages

File Name

ema_mail.kb

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


EMailSendMessage

File Name

ema_mail.kb

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


EMailShutDown

File Name

ema_mail.kb

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


EMailStartup

File Name

ema_mail.kb

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


EMailSystemTypeNum

File Name

ema_mail.kb

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


EmailTest

File Name

ema_mail.kb

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


EMailTestEventHandler

File Name

ema_mail.kb

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


HandleDeleteBtn

File Name

ema_mail.kb

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


HandleDumpBtn

File Name

ema_mail.kb

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


HandleGetreadBtn

File Name

ema_mail.kb

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


HandleGetUnreadBtn

File Name

ema_mail.kb

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


HandleListSelect

File Name

ema_mail.kb

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


HandleLoginBtn

File Name

ema_mail.kb

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


HandleLogoutBtn

File Name

ema_mail.kb

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


HandleReadBtn

File Name

ema_mail.kb

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


HandleSendBtn

File Name

ema_mail.kb

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


PerformAction

File Name

ema_mail.kb

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


PerformSelectAction

File Name

ema_mail.kb

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


StatusOfKMLMailCall

File Name

ema_mail.kb

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


UpdateLoginDialog

File Name

ema_mail.kb

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


UpdateLoginFields

File Name

ema_mail.kb

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


WriteMsgLns

File Name

ema_mail.kb

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