cc:Mail Mobile Developer's Documentation
Lotus cc:Mail Mobile for Windows Release 2


This documentation supplements the VIM API and
Import/Export documentation. VIM (Vendor Independent Messaging)
allows you to mail-enable applications and Import/Export allows
you to import and export messages and Directory entries. cc:Mail
Background as a standalone program is often used in conjunction
with VIM and Import/Export applications. See the VIM and
Import/Export documentation for details. 

This document describes how to use the cc:Mailr
Background component of Lotus cc:Mail Mobile for Windows to
mail-enable your applications specifically for mobile use. Refer
to the cc:Mail Mobile for Windows Getting Started Guide and
README file for more information on cc:Mail Background.

Mail enabling an application for a mobile mail system
differs in a number of ways from mail enabling an application
for a LAN mail system. With a mobile mail system

- Mail is sent to an outbox before it's delivered.

- A separate process (specifically, cc:Mail Background)
delivers mail to a post office and receives mail from a post
office.

- You communicate from a local post office to other post
offices.

To use cc:Mail Background as a standalone process,
you need to be familiar with the Windows development environment
(for example, .INI files and sending messages to applications),
and with cc:Mail and mobile products.

Note: Using cc:Mail Background as a standalone program in
third-party applications has not been tested by Lotus cc:Mail.
Exercise caution when using your application on a production
post office.

Using cc:Mail Background

You can communicate with cc:Mail Background in the
following ways:

- Using command-line parameters

See "cc:Mail Background Command Line" for
command-line syntax and a description of the parameters that
cc:Mail Background accepts.

- Using Windows messages

This requires Windows programming experience, and
a Windows client application to send and receive the Windows
messages.

See "cc:Mail Background Messages" for information
on message types.

- Using an .INI configuration file

The MOBILE.INI file contains everything cc:Mail
Background needs to know about locations and communication
methods. This file resides in the same directory as the Mobile
post office.

See "The MOBILE.INI File" for a description of
file values.

The WMAIL.INI file contains information cc:Mail
Background needs to preview message summaries (manually filter
messages). This file resides in the user directory (MBnDIR).

See "The WMAIL.INI File" for a description of the
applicable values.

cc:Mail Background Command Line

cc:Mail Background (CCBKGRND.EXE) can be started by a
user, by cc:Mail, or by another application. When a user starts
CCBKGRND, typically no parameters are provided, and the user is
prompted for the necessary information. When cc:Mail or another
application starts CCBKGRND, the following syntax is used: 

CCBKGRND WindowHandle CallType POPath UserName 

WindowHandle 
This is a handle to the cc:Mail client. Any valid
Windows handle is accepted.

CallType 
This command tells CCBKGRND which operation to
perform. See Table R-2, "cc:Mail Background Operations," for
details.

POPath 
This is the path to the local post office.

UserName (optional)
This is the user's name. 

If either WindowHandle or CallType are invalid,
CCBKGRND acts as if no parameters were provided and displays the
Login dialog box. Otherwise (assuming the POPath is valid), the
CallType command passed is executed.

A sample command line follows:

CCBKGRND 2053 1 C:\CCMOBILE\CCDATA Denise Allison

This example starts cc:Mail Background with the
following values:

WindowHandle = 2053
The window of the routine that's starting cc:Mail
Background.

CallType = 1
The STARTUP command (see Table R-2).

POPath = C:\CCMOBILE\CCDATA
The post office stored in the C:\CCMOBILE directory.

UserName = Denise Allison
The user Denise Allison.

cc:Mail Background Messages

Once CCBKGRND is started, it communicates with the
client program through Windows messages (see Table R-1).
CCBKGRND responds to CLIENT_CMD messages and sends back
PR_UPDATING_DB, PR_MAIL_UPDATE, and PR_END_UPDATING_DB messages. 

When CCBKGRND starts a connection session, it sends a
PR_UPDATING_DB message to the Windows handle that was passed to
it when you started cc:Mail Background. When CCBKGRND completes
a session, it sends a PR_END_UPDATING_DB message. During a
session, CCBKGRND sends a PR_MAIL_UPDATE every time a message is
sent successfully (deleted from the Outbox) or received.

Note: WM_USER is 1024 (0x4000). Numbers shown are
decimal.

Table R-1: Windows Messages 		

Action	 	   Message Type 	Description 

PR_UPDATING_DB 	   WM_USER+200 	        Informs your client
that Background is starting a session. 

PR_MAIL_UPDATE     WM_USER+201          Informs your client that
a message has been sent (WParam = 1) or received (WParam = 2). 

PR_END_UPDATING_DB WM_USER+202          Informs your client
that Background has finished a session. 

CLIENT_CMD         WM_USER+203           Sends commands and
information from your client to Background. 

cc:Mail Background Operations

You can use the cc:Mail Background operations in
Table R-2 in either of the following ways:

- Send a CLIENT_CMD message to cc:Mail Background with
the appropriate WParam value.

- Pass the value as a CallType in the command line.

Table R-2: cc:Mail Background Operations

Action	 	WParam Value 	Description 

STARTUP         1               cc:Mail Mobile is starting,
(cc:Mail Background will check the On Startup setting). 

SHUTDOWN        2               cc:Mail Mobile is shutting down
(cc:Mail Background will check the On Exit setting).  

ON_SEND 	3               Send a message (cc:Mail Background
will check the On Send setting). 

MAIL_CALL       4               Initiate a connection. 

SHUTDOWN_NOW    8               Shut down cc:Mail Background. Any
transfer in progress is terminated. 

LOCATION_CHANGE 9                Change locations. 

STOP 		10               Break connection but stay active.
This performs the same action as the Stop button. 

(Reserved)      11               Reserved by Lotus. 

MAIL_SEND       12               Initiate a send-only connection
(data in the Outbox is sent, no data is received).  

MAIL_RECV  	13               Initiate a receive-only
connection (data is received, data in the Outbox is not sent). 

(Reserved)  	14               Reserved by Lotus. 

START_BUTTON    15               Start cc:Mail Background. 

MANUALFILTER_CHANGE 16           Force update of Preview
Message Summaries. 

Initiating a cc:Mail Background Session

To initiate a cc:Mail Background session, you can

- Send one of the following commands (see the previous
section):

  - MAIL_CALL
  - MAIL_SEND
  - MAIL_RECV

- Choose the Start button in the cc:Mail Background
window.

Note: The Start button always sends and receives mail (versus
send only or receive only).

- Set one of the following schedule options and enable
the associated property in the MOBILE.INI file (see "Specifying
Scheduling Options"):

  - STARTUP
  - SHUTDOWN
  - ON_SEND
  - EnableSchedule (including setting the current
    time and date to call)

The MOBILE.INI File

This section describes how to set and maintain
location and communication-method information in the MOBILE.INI
file. The MOBILE.INI file is located in the same directory as
the post office, and stores location and communication
information. The post office database stores more generic Mobile
parameters (see "Post Office Database Fields"). 

MOBILE.INI is created when cc:Mail Mobile is first
run and contains the sections listed in Table R-3.

Table R-3: MOBILE.INI Sections 	
Section 	    Purpose 

[cc:Mobile] 	    Contains parameters that apply to all
Mobile operations. 

[cc:Locations] 	    Contains a list of user-supplied
location names. These names are used to create separate sections
that contain information  about each location. 

[LocationKey#]      Contains information about a specific
location. 

[cc:Communications] Contains a list of user-supplied 
communication methods. These methods define how
the computer will communicate with post offices to exchange mail
through cc:Mail Background. 

[CommMethodKey#]     Contains information about each
communication method.  

[LocationIcons]       Specifies which icons are available
for locations. 

[cc:DialStringSubstitutions]  Defines all string
substitutions (dialing rules) that are used in generating a dial
string from a telephone number.  

You can update the MOBILE.INI file by changing values
in the cc:Mail Mobile for Windows interface or by editing it
with a text editor. The following conventions are used to
describe the MOBILE.INI sections:

- Boolean means either a 0 (False) or a 1 (True)
- Number is an integer number, followed optionally by a
range in brackets (for example, [0-9])
- A range enclosed in braces, such as {1-4}, means to
choose a value between 1 and 4.

Note: Some values cannot be set in MOBILE.INI and must be
set in cc:Mail Mobile. See "Post Office Database Fields" at the
end of this document for more information.

[cc:Mobile]

Parameters in this section apply to all Mobile
operations.

Specifying the Default Locations and Communication Methods

CurrentLocationKey = LocKeyName
Specifies the location; LocKeyName refers to the
name in the [cc:Locations]  section, which is then used to find
the section heading. The default is LocationKey1.

DefaultLocationKey = LocKeyName 
Specifies the default location, which cannot be 
deleted; LocKeyName refers to the name in the [cc:Locations]
section, which is then used to find the section heading. The
default is LocationKey1.

DefaultCommMethodKey = CommKeyName
Specifies the default communication method;
CommKeyName refers to the name in the [cc:Communications]
section, which is then used to find the section heading. The
default is CommMethodKey1.

Customizing Login

ExpandedSetup = Boolean
Specifies whether the Login dialog box is
displayed in the larger (More) version or the smaller (Less)
version. Less is the default.

Specifying a Text Editor

TextEditor = d:\path\filename.ext
Specifies the text editor used when editing modem
or script files. NOTEPAD.EXE (on the path) is the default.

Specifying the Modem and Script File Path

Modem&ScriptPath = d:\path
Specifies the path used when searching for modem
or script files. The application's load directory is the default.

[cc:Locations] 

This section contains a list of user-supplied
location names, which are used to create [LocationKey#] sections
that contain information about the location. 

LocationKey# = LocKeyName
Each LocKeyName names a specific location, which
is then used as a section header for location-specific
information.

The special location referred to by the
DefaultLocationKey in the [cc:Mobile] section cannot be deleted.

[LocationKey#]

Each of these sections can contain the following
location-specific values.

Specifying the Communication Method

LocCommMethodKey# = CommKeyName
Indicates that a specific communication method is
enabled from this location.

Note: Answer (Accept) mode is supported only for the
first communication method defined in a location; the order is
defined in the [cc:Communications] section.

Specifying an Icon for a Location

Icon = InOutFlag, parameter
Specifies the icon to be displayed for this
location.
1 = Internal icon; the parameter is a resource
index.
2 = External icon; the parameter is the file path of
the icon file.
See also the [LocationIcons] section.

Specifying an Override Phone Number

PO.post office name = Override Phone Number

For each location, you can specify a single
dialing-string number to override the automatically computed
dialing strings. Typically, the number of the post office 
(obtained from the Directory Address field for the post office
you're dialing) is used, along with the dialing string that you
want to use. 

If the value in the Post Office field of the
Override Phone Numbers dialog box equals a post office name in
this section, the Dialing Rule check box is deselected, general
dialing rules are not applied, and the override phone number
appears in the Sample Dialing String field.

Note: The "PO." is used to eliminate conflicts with post
office names like "LocIcon,"  "OutsideLine," "Frequency," and so
on.

For more information, see "Overriding Phone
Numbers" in the cc:Mail Mobile for Windows Getting Started Guide.

Specifying General Dialing Rules

The following four parameters (general dialing rules)
are used to convert phone  numbers to dialing strings for each
post office to be contacted (unless overridden):

OutsideLine = String
PhonePrefix = PrefixName
PhoneSuffix = SuffixName
ExcludeAreaCode = String

The format for the call that cc:Mail Background
will make is

[Outside Line] [Phone Prefix] [PO Phone Number]
[Phone Suffix]

The number to be dialed appears in the Sample
Dialing String field in the Location Setup dialog box. cc:Mail
Background excludes the area code if ExcludeAreaCode equals the
PO Phone Number area code. 

Specifying the Dialing Mode

DialMode = {1-3}
1 = Tone
2 = Pulse
3 = Manual
Specifies how phone dialing works. Use tone or
pulse as instruction to the  modem (ATDT or ATDP). Use Manual to
ask the user to connect manually on the phone before choosing OK
to start the connection session.

Specifying Scheduling Options

The following parameters enable call scheduling:

OnStartup = Boolean
If True, the cc:Mail Mobile client tells cc:Mail
Background to connect and check for mail whenever the client
starts.

OnExit = Boolean
If True, cc:Mail Background connects and checks
for mail whenever cc:Mail Mobile terminates.

OnSend = Boolean
If True, cc:Mail Background connects and checks
for mail whenever a message is posted to the Outbox.

EnableSchedule = Boolean
Tells cc:Mail Background whether or not to make a
timed call. If  EnableSchedule is False, cc:Mail Background
ignores the OnHourly, OnDaily, and OnWeekly parameters. 

Frequency = {1-3}
Tells cc:Mail Background how often to make the
call (if a schedule is enabled).
1 = Hourly
2 = Daily
3 = Weekly

Time = hh,mm,ampm
If Frequency equals Hourly, then Time is the
number of minutes past the hour to call. 
If Frequency equals Daily or Weekly, then Time is
hh:mm ampm (a time of day, in 12-hour format).

Days = BSun,BMon,BTue,BWed,BThu,BFri,BSat
If Frequency equals Weekly, this parameter
specifies whether cc:Mail Background should call on the days
indicated. The values are seven Booleans, where if the Boolean
is True,  the call should take place on that day (for example, 
calling Monday through Friday but not on weekends would lead to
values 0,1,1,1,1,1,0). If Frequency equals Hourly or Daily, Days is ignored.

[cc:Communications]

This section contains a list of user-supplied methods
that define the exchange of mail between the computer and the
post office. As in [cc:Locations],  [cc:Communications] contains
a list of method names. Information about each method is
maintained in a separate [CommMethodKey#] section.

Note: The order of the methods defined in [cc:Communications] is
important,  because it indicates which methods cc:Mail
Background tries first when multiple methods can reach a given
post office.

CommMethodKey# = CommKeyName
Each CommKeyName names a specific communication
method, which is used as a section header for method-specific
information.

[CommMethodKey#]

Each of these sections contain method-specific
information. Not all of these parameters apply to each
communication method.

Specifying the Communication Type

The CommType parameter specifies the type of
communication used.
CommType = {1-11}
1   =   Modem
2   =   NetWare (SPX)
3   =   TCP/IP
4   =   (Reserved)
5   =   Wireless (packet)
6   =   X.25
7   =   ISDN
8   =   PBX
9   =   (Reserved)
10  =   (Reserved)
11  =   Direct Connect

Note: Values 4, 9, and 10 are not supported in this
release.

Specifying the Speed

Speed = 1200; 2400; 4800; 9600; 14,400; 19,200;
38,400; 57,600; 115,200
Specifies the speed at which the software
communicates with the hardware. This parameter is used with the
following communication types: Modem, Wireless, X.25, ISDN, and
PBX. See the modem file for the default value.

Specifying the Communication Port

ComPort = {1-4}
Specifies the physical communication port to use.
This parameter is used with the following communication types:
Modem, Wireless, X.25, ISDN, and PBX. The default is COM1.

Specifying the Script File

Script = Filename.ext, Description
Defines which script file will be used. Script
files are used to communicate over public data networks. Refer
to "cc:Mail Script Files" in Appendix F of the cc:Mail Mobile
for Windows Getting Started Guide for more information on script
files. This parameter is used with the following communication
types: Modem, Wireless, X.25, ISDN, and PBX.

Specifying the Modem File

Modem = Filename.ext, Description
Defines the commands that cc:Mail Mobile uses to
communicate with a specific modem. Refer to Appendix B of the
cc:Mail Mobile for Windows Getting Started Guide for more
information on modem types. This parameter is used with the
following communication types: Modem, Wireless, and X.25.

Specifying the Speaker Volume

SpeakerVolume =  {1-4}
Controls the volume on the modem's speaker. Not
all modems support this feature. This parameter is used with the
following communication types: Modem, Wireless, and X.25. The
default is Off.

1 = Off
2 = Low
3 = Medium
4 = High

Specifying the Timeout

Timeout = Number
Time in seconds to wait for either

- An answer (specifically, a proper connect
response) from the post office that you're calling 

- A data packet

If time expires in the first case, cc:Mail
Background returns "No carrier detected." If time expires in the
second case, cc:Mail Background returns "Data connection lost."
The default is 30 seconds.

Specifying ASCII Mode

AsciiMode = Boolean
Determines if cc:Mail Background communicates
using 7-bit data or 8-bit data. This parameter is used with the
X.25 communication type only. 

Specifying Parity

ParityType = {0-3}
Determines parity when ASCII mode is enabled. The
default is None.
0  = None
1  = Even
2  = Odd
3  = Mark

Specifying the Speed Lock

Lock = Boolean
If True, cc:Mail Background communicates with the
modem only at the speed specified in the Speed parameter. If
False, cc:Mail Background uses the connection speed. The correct
value for this parameter depends on your modem type. See the
modem file for the default value.

Specifying Error Correction

ErrorCorrection = {1-4}

Defines the type of error correction cc:Mail
Background uses:

1 = Automatic
Typically the default. Automatic specifies that
cc:Mail Background should use whatever it thinks is best (if
Speed is less than or equal to 2400, it uses low-speed error
correction; if Speed is greater than 2400, it uses high-speed
error correction).
2 = Low-speed
3 = High-speed
4 = None
Indicates that cc:Mail Background should use no error
correction and assume that the transport itself will provide
error correction (for example, a TCP/IP transport or a Wireless
transport doesn't require error correction).

[LocationIcons]

This section specifies which icons are available for
locations. The format is 

Icon# = FullPathName

[cc:DialStringSubstitutions]

This section defines all string substitutions
(dialing rules) used to generate a dialing string from a
telephone number. The telephone number is generated by taking
the given dialing string and filling in the variables with
values, all of which come from the post office database (see
"Post Office Database Fields" later in this document).

The following strings are samples:

ATT Long Distance=102881 [AreaCode] [LocalNumber]

MCI Long Distance=102221 [AreaCode] [LocalNumber]

France, Int'l
From=19,,[CountryCode][CityCode][LocalNumber]Dialing rules
substitute values for variables. The variables are strings
enclosed in brackets ([]). A list of the  preassigned variable
names follow. If the variable is not in this list, it is assumed
to be in the [cc:DialStringSubstitutions] list.

[CountryCode]
If the phone number has a country code associated
with it, it replaces this variable.

[AreaCode]
Replaced by the telephone number's area code.

[CityCode]
Synonym for [AreaCode].

[LocalNumber]
Replaced by the local telephone number.

[CallingCardNumber]
Replaced by the calling-card number.

The WMAIL.INI File

Manual filtering, or previewing Message Summaries, is
handled by two parameters in the [cc:Mail] section of the
WMAIL.INI file.

ManualFilter = Boolean
If True, the Message Summary dialog box appears
while messages are downloaded.

ManualDelay = Number [10-60]
Time in seconds to display the Message Summary
dialog box for each message. 

Viewing the Session Log

The Session Log  can be accessed just as any other
folder can be accessed (through the cc:Mail Mobile interface,
through a VIM application, or through Import/Export). See the
appropriate documentation for instructions on accessing folders. 

The last Session Log can be found in the SESSION.LOG
file in the post office database directory.

Post Office Database Fields

The following parameters are shown in .INI format but
are actually stored in database format. You must use the cc:Mail
Mobile interface to modify these fields. Refer to the following
table and the cc:Mail Mobile for Windows Getting Started Guide 
(references are provided in parenthesis in the following 
table) for information on these parameters.

Table R-4: Post Office Database Parameters 	

Parameter 	                How Used 	

meRetries = Number [0-9] 	Number of times to retry
if a connection fails. ("Setting Retries") 

meInterval = Number 		Time (in seconds) to wait
between retry attempts. ("Setting Retries") 

meSendReceive = {0-2} 	        0 = Send and receive messages
on each connection (the default)1 = Send messages only
                                2 = Receive messages only 
("Sending Messages")

meSaveSessionLog = Boolean 	If True, save the
Session Log message in the Session Log folder at the end of the
connection. ("Setting cc:Mail Background Parameters") 

meDiagnostics = Boolean 	If True, displays extra
diagnostic information. ("Setting cc:Mail Background
Parameters") 

meToneOnComplete = Boolean 	If True, sounds off at
the end of the connection. ("Setting cc:Mail Background
Parameters") 

meEnableRestrictedDisplay = Boolean 	If True,
doesn't display PO numbers header information on the received
messages, or allow the state of Verbose or Manual Filter to be
changed in cc:Mail Background.("Setting cc:Mail Background
Parameters") 

meAnswerMode = Boolean 	If True, while waiting to
make a connection, cc:Mail Background goes into Answer (Accept)
mode, waiting for a call from another post office or Mobile
user. ("Setting cc:Mail Background Parameters") 

meConfirmUpdates = Boolean 	If True (the default), 
prompts before processing System Update messages.  ("Managing
System Updates")  

HomePO = PostOfficeName  Taken from the Directory
Address field. ("Changing Your Home Post Office Address") 

meCallingCardNum = Calling Card information (32
bytes)	Stored in the database for security. ("Setting a
Calling-Card Number") 



Copyright (c) 1994 by cc:Mail, Inc., a wholly owned
subsidiary of Lotus Development Corporation. All rights
reserved. The distribution and sale of this product and guide
are intended for the use of the original purchaser or assignee
only.

The cc:Mail logo is a registered trademark and
cc:Mail is a trademark of cc:Mail, a wholly owned subsidiary of
Lotus Development Corporation. Lotus is a registered trademark
of Lotus Development Corporation. NetWare is a registered
trademark of Novell, Inc. All other product names are owned by
their respective companies.

