Telephony-based email application

Rochester Institute of Technology

RIT Scholar Works

Theses

Thesis/Dissertation Collections

1999

Telephony-based email application

Perdana Darta

Follow this and additional works at:

http://scholarworks.rit.edu/theses

This Thesis is brought to you for free and open access by the Thesis/Dissertation Collections at RIT Scholar Works. It has been accepted for inclusion in Theses by an authorized administrator of RIT Scholar Works. For more information, please [email protected].

Recommended Citation

Telephony-based

Email Application

By

Perdana Darta

Project

submitted

in

partial

fulfillment

of

the

requirements

for

the

degree

of

Master

of

Science in Information

Technology

Department

of

Information

Technology

Rochester Institute

of

Technology

Rochester Institute of Technology

Department of Information Technology

Master of Science in Information Technology

Project Approval Form

Student Name

:_--,P,-,e~r-=d~an....!.::a~D=:...a~rt~a::!--

_ _

Student Number:

_

Thesis Title:

Name

Telephony-based Email Application

Project Committee

Signature

Date

Prof. Rayno Niemi

Chair

Mr. Robert Hermanns

Committee Member

Copyright 1999 Perdana Darta

Table

of

Contents

I. Abstract 1

II. Goals oftheProject 2

III. ProjectOverview 3

in. 1. HardwareRequirements 3

in. 1.1. Voice Modem Driver 3

DI.2.

Programming

Language 3

m.2. 1. TAPIBrowserver. 1.4 4

HI. 3. Windows Application

Programming

Interface

(API)

4

m. 3.1. Windows API Text Viewer 5

ni.3.2. ImplementationsofWindows APIs 5

IV. FunctionalDesign 8

IV. 1. Configuration Steps 10

IV.2. Placean

Outgoing

Call 14

IV. 3. Handlean

Incoming

Call 16

IV. 3.1. Answeran

Incoming

Call

Manually

16

IV.3.2. Answeran

Incoming

Call

Automatically

16

rV.4. SendtheCaller's MessagetoanEmail Address 18

IV.5. CallAdministrations 22

IV.5. 1. Playback New / Old Messages or

Greeting

Messages 22

IV.5.2. Delete Old Messages 23

IV.5. 3. ChangetheAnnouncement

(Greeting Message)

23

V.

Telephony

Application

Programming

Interface

(TAPI)

25

V. 1. Basic Typical TAPI Functions 25

V.2. Media Stream 26

V.3.DataStructure 26

V.4. InitializeTAPI 27

V.5.MonitorMessages from TAPI 27

V.6. Open Line / Phone Devices 27

V.7.ReceiveCalls 28

V.8. Monitor Digit DTMF 28

V.9. PlacetheCall 28

V.ll.Toll Saver 29

V.12.

Drop

theCall 29

V. 13. Deallocate Call Handles 29

V. 14. Close Line / Phone Device 30

VI. Multimedia Control Interface

(MCI)

31

VI. 1. MCICommand Messages 3 1

VI.2.WAV Audio File Format 32

VI.3.

Detecting

aProper

Recording

andPlayback Modem Device 32

VI.4.

Recording

aMessage 32

VI.5.

Saving

aMessage 33

VI.6. PlaybackanAnnouncement

(Greeting Message)

33

VI.7. Detectand

Display

MCI Error Codes 34

VII. Remote Access Service Application

Programming

Interface (RAS

API)

35

VII. 1.

Starting

aConnection 35

VII.2.

Terminating

aConnection 35

VII.3.

Detecting

RAS Error Messages 36

VE.4. Timer 36

VIII. Mailer 37

VIII. 1. Windows Sockets

(Winsocks)

Control 37

VIII. 1.1. Multipurpose Internet Mail Extensions

(MIME)

37

VUI. 1.2. Base64

Encoding

38

Vm. 1.3MIME

- base64

Encoding

38

VIII.2.

Messaging

Application

Programming

Interface

(MAPI)

as aMAPI Client 39 VHI.2. 1. MAPIClient

- MAPIServer (Netscape

Messenger)

40

IX. Conclusions 41

Citations

Appendix

Attachment

"Incoming

Call Flow Chart"

I.

Abstract

The aim ofthis project is to provide user to gain access of

telephony

services such as

placing an _{outgoing calls, answering calls, playing back} an announcement to the callers, recording caller's _{messages, playing back} recorded messages and

finally

_establishing a dial up connectiontosendtherecordedmessageto an e-mail address.

To do _that, the application will be

implementing

and _combining some of Windows

Application

Programming

Interface

(API)

functions asfollows :

1.

Telephony Programming

Interface

(TAPI)

ver. 1.4.

2. Multimedia Control Interface (MCI VisualBasic 6's Multimediacontrol).

3. Remote Access Service (RAS

API)

4.

Messaging

Application

Programming

Interface (MAPI Visual Basic 6's MAPIcontrol).

II.

Goals

of

the

Project

The primary focus ofthe above integration isto develope aclient-side application

(using

Visual Basic

6)

within the _{Windows 95 operating} system that can function like a telephone

answering machine where attheend ofthecall session the caller can sendtherecorded message outtoanemail address.

2-III. Project

Overview

II.l. Hardware

Requirements

This application needs an _{analog line} telephone device and runs on a workstation with

Windows 95. Besides that the applicationneeds a speakerphone voice-data modem supported

by

Voice Modem driverand a sound card as well (withexternal speakers and a_microphone) to_play backandrecord

callers'

messages.

IH.1.1. Voice Modem Driver (Unimodem/Voice

version

4.10.1343)

There are two common types of modem drivers i.e. Unimodem and Unimodem I Voice.

Both are called a TAPI Service provider

(TSP)

that is

basically

a driver to allow TAPI to communicate with

telephony

hardware.

Unimodem driver is a standard TSP provided

by

Windows that supports _any modem

when_{placing data}calls. IftheTAPIcompliant applicationis usingtheUnimodem drivertoplace a voice_call, theuserhastodeterminetheprogress ofthecall (whetherthecall completes or_not)

by invoking

a certainbuttontoendthevoice call. It showsthatnot all modems canhandlevoice calls.

Instead, Unimodem/Voice,

a released version of Unimodem to support voice modems under Windows

95,

is designed to answer calls and be able to play/record wave files over the phone line andthe handset. It also detects a

disconnecting

signal whenthe call session ends so the application does not _rely on human intervention to press a certain button when the call completes.

TAPI Browserversion 1.4underWindows 95 willbe helpful forthedevelopertoobserve

exactly what a given TSP is capable _of, how it works and its behaviors especially using

Unimodem/Voice. The behavior of other service providers will _vary

depending

on the

capabilitiesofthehardware

being

used.

The developers can check the TSP version

(especially Unimodem/Voice)

being

used in theirmachine

by

_clicking the "version" tab atthe properties ofthe

Unimdm.tsp

file in

directory

Windows/Systems. This application is using Unimodem / Voice version 4.10.1343 that can be

downloaded from ftp://ftp.microsoft.com/Softlib/MSLFILES/UNIMODV.EXE

III.2.

Programming

Language

Even though the Windows API based application can be developed using

C++, Java,

etc.,the authorfeels moreknowledgeable using Visual Basic version 6than those_programming languages above.

3-The VB 6 also provides some controls which

directly

manage low level

Windows' API

functions.

By

_setting properties and

invoking

methods ofthe controls, it is much easier to build

Windows'

API

-basedapplication.

For example, the VB 6's Multimedia control

(MCI)

manages _recording and _{play back} messages rather than

building

low level wave form APIs. The VB 6's MAPI control provides messaging services to allow an application to compose and send an email rather than

building

low _{level messaging APIs.}

Finally

the VB 6's Winsocks control will let the application establish and maintain a direct connection to a remote server so the application can exchange data (i.e. email_messages) ratherthan

building

low level Winsock APIs.

This application also needs Netscape Messenger version 4.5 or newer (one of MAPI

compliant mail _servers) when _sendingan email. It functions as a messagetransport (mailer the

mail _server) that delivers an email composed

by

this application (the mail _client) to a remote

server.

m.2.1. TAPI Browser

ver.

1.4

To observe how TSP _works, theTAPIbrowser version 1.4 for Windows 95 is atool to

query all available TAPIfunctions so theuserwill know howto _properlymanage and use each TAPIfunction such as TAPI'sconstants, data structures in responseto the

telephony

signal sent

by

alocal exchange. The TAPI Browser (included inthisprojectas an _attachment) willreturn all required parameters ineach requireddatastructure.

By

_usingthis,theuser can

directly

get access to

telephony

services such as how to place an _outgoing calls

(lineMakeCalls(

)),

to _query the

modem capabilities

(lineGetDevCaps(

)),

to detect total modems in associated machine

(linelnitialize(

)),

etc.

Thisis an exampletomake some standardTAPIcalls_using asinglemodem :

linelnitialize(

),

lineOpen( )

/*

usedevice 0

*/,

HneMakeCall( )

,

lineDrop(

)

lineDeallocateCall(

),

lineClose(

),

lineShutdown( )

This browsercanbe downloaded from

FTP://ftp.microsoft.com/developr/TAPI)

III.3. Windows

Application

Programming

Interface

(API)

The Windows Application

Programming

Interface

(API)

is a set ofpredefined functions built into the DLLs such as

TAPI32.DLL,

RasApi32.DLL,

winmm.dll, etc. that make _up the Windows operatingsystem. A DLL (dynamic link

library)

iscompiled codethatcanbe accessed

only

by

other applications at runtime. This standardizes the _programming community, as it allows the same code to be used repeatedly. End users can't

directly

access these functions.

However,

developerscanaccess thecode writteninthe DLLsthrough theAPI and usethis code

in theirprograms. This allows developerstouse _existing codein theDLLs and savetime in the

programming developmentcycle.

Touse andaccess theWindows APIs in Visual

Basic,

the developerscan use theDeclare

Declare Function lineMakeCall Lib "TAPI32.DLL"

(ByVal hLine As Long, lphCall As _Long, ByVal IpszDestAddressAs

String,

ByValdwCountryCodeAs

Long,

lpCallParams As

Any)

As Long.

Syntax :

Declare : A keyword

indicating

an external procedure declaration

Function : Theproceduretype

LineMakeCall : Thename ofthisparticular external procedure

Lib : Akeyword

indicating

theDLL inwhichto locatethefunction

hLine,

lphCall : Anargumentvariable

lpCallParams : whichis aWindows-defined type, CALLPARAMS

As

String

/ As

Long,

As

Any

:keywords

indicating

argumenttype

Long

: A functionreturntype

Windows- definedtypes/

structures

A structure is a _group of variables organized under one name. This is used to pass

information between the Windows API and the _requesting application. When certain variables

are _grouped, the application can create instances of the _type, as the application would create a variable. For example : line Make Call function needs the CALLPARAMS datastructure. The

developers can find the definition of that Windows-defined types within the API Viewer tool provided

by

VB orwithinthedocumentation oftheWindows Software Development Kit

(SDK),

whichcomes ontheMicrosoft Developers Network CD-ROM included in VB.

IH.3.1.

Windows

API Text Viewer

To avoid an error when

inadvertently

_writing parameters of Windows API and to save

valuable _{programming time,} the developers can make use of the TAPI Text Viewer shipped

which Visual Basic (in

"add-ins"

menu), which enables developers to cut and paste API

functions,

constants,andWindows-definedtypes rightintothecode.

III.3.2.

Implementations

of

Windows

APIs

Thisproject uses five Windows

APIs,

which are

briefly

described inthe

following

section

1. The

Telephony

API

(TAPI)

:

The TAPI is an application _programming interface in the Windowsplatform that allows an application to provide access to

telephony

services such _{as, making} a _{call, answering}

incoming

call,

detecting

and_{generating DTMF digit from /}to local_exchange, etc.The TAPIwill

needs to _query the TAPI functions to determine the capabilities of both that are _actually available.

2. The Windows Multimedia Control Interface

(MCI)

:

This application uses the Windows Multimedia Control Interface to interact with

multimedia hardware. Hardware can consist of _any media devices that Windows supports i.e.

audio CD _players, wave _audio, etc. The application issues theMCI's standard commands, works

with the specific driver

(Unimodem/Voice)

to supportthe voice modem device in use, and then

translates these commandsto theexactsignals required to _carry outthe action such as_{play back} aWAV

file,

recorda

callers'

message, andsaveit.

One wayto send commandsto theMCI device is touse thefunction mciSendCommand. Although this function is not a part of

VB,

this function is part of Windows Application

Programming

Interface

(API),

the huge collection offunctions thatprovides most of

Windows' capabilities.

The second method for sending MCI commands is using Visual Basic's Multimedia

control. When displayed on a

form,

this control provides an _array of_{buttons for controlling} a multimediadevice.

3. The

Messaging

API interface

(MAPI)

:

Visual Basic'sMAPIcontrol willallowtheapplicationto send a message with or without

an attachment to a recipient mail address. This application, called the MAPI _client, will work

togetherwith aMAPIServer (i.e. Netscape Messengeror other_mailer)that_{has responsibility for}

messagetransport

(moving

messagesto andfromremoteservers and_clients), message storage(a mailbox before mail clientreads the

incoming

_message) and address book (contains a particular mailingaddress/addressee).

After the callers press # 3 (to send their message to an email address), the application

will_{be activating}theVB's MAPI_control,onceaninternetconnection exists.

4. The WindowsSockets

(Winsocks)

As analternative_usingtheMAPIservices to send an email, theapplication can make use

of VB's Winsocks control. It allows the application to create and maintain a connection to a remote server

by

_opening sockets on other computers and _{accessing Transport Control Protocol}

(TCP)

networks services.

Using

the _connection, both computers can transfer data between themselves_usingthesocketwhich theapplicationhas opened.

5. The Remote Access Service (RAS

API)

:

The RAS API functions will let the applications establish and terminate a dial up

connection to theremote serverwithout

displaying

aDial

Up Networking dialog

box. The RAS functions will _query a connection information such as the name ofthephone-book _entry (which

modem)usedtoestablishthe_connection,user name and passwordto

log

ontoremote server, and

alsoremoteserver's phonenumberfrom

"Login"

IV. Functional Design

This is themain menu whentheapplicationruns.

TAPI. MCI.RASAPI.MAPI andWinsocks File Mail Tools _Help

System OFF_{On}

I

f AutoAnswer l~~

EnableMail

?m

pNumofRings I { 2rings

ModerjTurn

0n/0ffapplication[K56Data,Fa:<,Speakerph

^|

1

r 4rings

Mic

-Speaker F Default Record-Playback Device

17 Default

Answer Dialr3u _HangUp

1 Fie Name

'

Remote Digit

.

You have: 1 New_Msg[s)

Playback_Msg DeleteMsg

p10-_{Phone 81 Unknown Message}

-PhoneNegAF'Ifl} 009-_{Phone80,HookSwitchDevsSupported:}

-HANDSET SPEAKER

008-_{Phone 80PhoneName:-RockwellSoftK5GData.Fax,SpeakerphoneP} 007-_{Phone 80supports ver1 0004}-PhoneNegAPI

00S-_{Line 81 LineName:-SupraExpress336i PnP Voice}

Ti

+

l

I

?!

Figure4.1. The MainMenu

Thesearefunctionsthat theuserscanperform :

1. Placean _outgoingcall.

2. Answeran

incoming

call

(manually

-press

"Answer"

buttonor automatically).

3. Playbackan announcer withthreemenustothecallers. Press #1 :to

hang

_upthecall.

Press #2 : toplaybackacaller'smessage.

Press #3 :tosendtherecorded messagetorecipient mailaddress.

4. Recordcaller's message and saveitinthesamefolderwheretheapplication resides.

[image:14.589.190.475.150.506.2]

6. Playbackrecorded message

directly

fromthe application orfromthe telephone line

by

press #2.

7. Deleteoldmessages

8. _{If necessary} user can change the _greeting message

by

_recording the new _greeting and

overwritingto theold one.

9.

Automatically

_{launch dial up} connection and end the recorded message to specified email

address_usingeitherNetscape MessengerorWindowssockets.

IV.

1.

Configuration Steps

This flowchart details how the user accesses to the

functionality

of the application

(menus). Seetheflowchartasfollows :

Run Application 1.

3.

5.

6.

enumerate,initializeand

display

thevarious modem's capabilities

(calllinelnitializeO,callphonelnitializeO, callEnumLineDev(),

callEnumPhoneDev() inmdlTAPIFunction.bas).

countand

display

unread_message(s) thatresidesinapplication'sfolder

(Dir()

infrmTAPLfrm).

detectand

display

wave audiodevice

-soundcard/voicemodem

(waveOutGetDevCaps()

in frmTAPLfrm).

terminateallactivedial upconnections

(callHangUp()

in mdlTAPIFunction.bas).

closeWinsocks TCPconnection.

set applicationdefault : manual _answer, disabled mail, length of recordable message= _10sees,number of rings=2_rings.

System ON

1. openline /phonedevice_{(calllineOpenO,callphoneOpen())}togetline

(lphLine)

/phone

(lphPhone)

handletobeusedforsubsequent operations.

System OFF

1. terminateall active_{dial up}connections

(callHangUp()

in

mdlTAPIFunction.bas).

2. closeWinsocks TCPconnection.

3. close an openMIMEbase64encodedfile.

4. close an open line / phone device

(calllineCloseO,

_{callphoneClose()} in mdlTAPIFunction.bas).

Select :_line,

phone, wave device

1. selectmodem,mic

- _speaker

phone,wavedeviceoftheavailable modeminassociatecombobox.

2. Ifnot_usingthe default userhasto select mic speaker modem device wavedevice thatallows theapplication to _{play back}and record _{greeting /}

incoming

message over the telephone line otherwise all greetings will be played back in the local sound card

Forexample:

Select : "Voice Modem to _{play back} greetings and record

caller's messageto/ fromoverthetelephoneline.

Select : "Sound Card To play backgreetings tolocal sound card andthiswon't recordcaller's message

if "AutoAnswer1'

ischecked :

-. the application will _{automatically} answer an

incoming

callbasedonnumber of rings(the default is 2rings).

.

Play

back greeting ("greeting.wav")tothecaller. . After greeting ends it will

automatically record caller's message based on

predetennined length of message in

"Msg

Length"

of "Mail" menu (the length

messagedefaultis 10sees).

. An

incoming

message will be saved with the

beginning

of the file name is "New_& date &time&p/m.wav"

basedonthedateandtimeitrecorded.

. After saving the recorded message, it plays back the second greeting

("greeting2.wav")

to informthe callerif he wants to _{play back}recorded message

(by

pressing digit # 2). . Thecallercan

hang

upthecall session

by

_{pressing digit # 1}.

. If the caller does not make an action within 40 seconds

(tmrHangUp

in

frmTAPLfrm)

after the second _greeting message played, the application will

automaticallyterminatethecall.

if "EnableMail"

ischecked :

The application will_{play back}

"greeting23.wav"

to tell the caller thathe can _play

back his recorded message (press digit

#2)

or

directly

send it out to the owner

application email address(press digit #3).

. The application will send it out using either Netscape Messenger or Windows Sockets basedon user's choicein "SetUp"

of "Mail" menu.

-. Ittakes15 sees(aftercaller pressesdigit

#3)

beforetheapplicationfires_{up dial up} connection(callRasDialO).

-. User hastoprovide username, passwordand phone number oftheremote server in "SetUp"

of

"Mail"

menu. Theseparameterswillbeusedfor establishing dial

upconnection.

. Once dial up connection established, either Netscape Messenger or WinSocks control will send it out based on mailer parameters (such as destination /

originatingemail address and server name).

-. After sending message, it automatically close MAPI services (if using Netscape

Messenger)

orTCP connection _{(if using WinSocks control)} and terminates the dial upconnection(callHangUpO). Sothe aplication will_{be ready} toreceive an

incoming

callorplace an_outgoingcall.

Set the number of rings before the application will

automaticallyansweran

incoming

call_{(the default is 2 rings)}

From "Mail"

menu:

X

Setthelength ofthe recordable messageforeither 10sees (154

kb)

or35 sees(544 kb).

From "SetUp"

in"Mail" menu

The defaultofthemaileris Windows Sockets.

1. Iftheuser choosesWinsocksasamailer,

Theusermust providetheremoteservername.

Theuserdoesn'tneedtoconfigureNetscape Messenger.

2. iftheuserchooseNetscape Messengeras amailer :

. Usermust configureNetscape Messenger firstasfollows : a. Open Netscape (ver

4.5)

->click

"Edit"

menu->click

"Preferences" ->

->click "Mail &Newsgroups''

->locate "Use Netscape Messenger from MAPI basedapplication"

and checkit if it'sunchecked->closeNetscape.

b. Make sure that destination email address _{is already} available in Netscape AddressBook,ifnot_trytocreateit in it.

. Netscape Messengerasamail serverwilltake80 sees(basedonpredetermined

timer

#2)

tosend the recorded message. This timerwill give an enough time to allowtheNetscape Messengertosendthemessagetotheremoteserver.

From "SetUp"

in "Mail"

menu

User name,Password,

Phone#, Modem,

Destinationmail_addr, Originatingmail addr

Servername

Usermust provide all mailerparameters.

The defaults are available

by

_alternating

button.

'Cancel / Default"

Answer _{-phisbutton isenabled whenthereis}

an

incoming

call. If "AutoAnswer"

ischecked, thisbuttonwill_{automatically}call a

specificfunctionasfollows (seeat_{mdlTAPILine.bas)}

1. CallphoneSetHookSwitch() to enablemodem speaker so theuser canhear a caller voice andtodisablemic ofthemodemso thecallercan't monitor user voice.

2. CalllineAnswer

())

toopen a connectionbetweenapplication andthecaller.

3.

CalllineMonDigits()

tomonitor callerresponse when_pressing a certain digit

DTMF

4.

CallGreetingO

to_playgreeting

("greeting.wav")

5.

CallMCIRecMsgO

torecordcaller message fora certain message length (10 sees as a

default)

12-If "Auto Answer"

is unchecked, the application will alert user

by

_sounding a

ringingcallsotheuser can pressthisbuttontoansweran

incoming

call.

Dial Pad

Toplace an_outgoingcall.

This action will launch "Dial Pad"

window so the user can

enter a letter or numeric digit of the phone number (phone # default is 1800Marinel).

All letter entries will be converted to numeric value in

mdlSupport.bas(callConvertStringToDigits())

Hang Up This action will

hang

_up the call session

by

calling

calllineDropO(seeat_{mdlTAPIFunction.bas)}

PlayBack_Msg

. To play back a greeting file or a caller message "New_ &

date &time&a/p.

wav"

- _prefixedfile_name.

. Itwill openMultimedia Control Interface

(MCI)

control and a certain folder

where allrecordedmessageand_{greeting files}reside.

. It will rename the

"New_*.wav"

prefixed file name to "Del_*.wav"

prefixed file name

(callRenameMsgO

in _{mdlSupport.bas)} and also subtract new messagecounter.

Save_Greeting -.Tosavea_greetingcreated

by

theuser(seeatfrmTAPLfrm).

-.Itwill open a certainfolderwheretheuser cansavethe

greeting

by

overwritingtheold_{greeting (for}ex.

"greeting.wav", "greeting2.wav" and"greeting23.wav").

Delete_Msg -. To deleteall recorded messages

("Del_*.wav)

thathave been playedback

(callDeleteMsgQ

in_{mdlSupport.bas)}

From "Modem SetUp"

in"Tools"menu

Modem Set_Up

. To configure a particular modem

(calllineConfigDialogO

in mdlTAPIFunction.bas)

by

launching

cofiguration

dialog

window.

From "Exit"in"File"

menu

Exit To exitfromthe activeapplication.This action will terminate

line / phone _device, dial _up connection

(calllineCloseO,

callphoneClose(), caliHangUpO), close TCP connection if it existsandunloadallopenforms (seeatfrmTAPLfrm).

IV.2.

Place

an

Outgoing

Call

1. Runtheapplication (Fig. 4. 1. The Main Menu).

2. Selectthe available modemtobeusedtoplace an _outgoingcalls (ifthe application has more

than one modem installed). Onceselectedthis modem will be answering

incoming

call (Fig. 4.2. Modem Option).

TAPI, MCI,RASAPI. MAPIandWinsocks

File Mail Tools _Help

UHxj

System OFF_(On)

I

f

Auto Answer f Enable Mail

Modem _{5b Data.Faa.bDeakerDhonePC Moder}

RockwellSoftK5bData.Fax.SDeakerDhone

Mic Sneaker SupraExpress 336iPnP Voice

Numof

Rings-( _2rings

C 4rings

[image:20.589.159.457.211.317.2]

17 Default

Figure 4.2. Modem Option

3. Checkthe "Microphone Speaker" and "Record

-Playback Device" checkbox as a default

instead of _selecting the microphone speaker and wave device option (Fig. 4.3.1. and Fig.

4.3.2.). This will let the application _{automatically specify} the associated microphone

speaker and wave device based on the selected modem (Fig. 4.3. Microphone Speaker and

Wave Device Option).

? x

File Mail Joels Help

System OFF_(On) 17 Auto Answer 17 EnableMail

Numof

Rings-(* 2 rings

Modem _{[RockwellSoftK56Data,Fax,Speakerph ?!}

j

r brings

Mic-Speaker

f~

Default Record- Playback Device j~"

Default

iii. SpeakerPhone Modem

Mic-_SpeakerMdm

[RockwellSoftKSG

DataJax.SpeakeJ

Ej

FileN

Remc

Rec-PlaybackDev

GameCompatibleDevic

OK Youh

Playback_Msg Delete_Msg

Figure4.3. Microphone- Speaker

andWave Device Option

[image:20.589.158.445.439.664.2]

.Speaker Phone Modem

?H

Mic

-Speaker Mdrn

Rec-Playback Dev

[Modem

lata.Fax.SoeakerohonePC Moderr

Rockwell SoftK5GDataFax.SoeakerDhc

[image:21.589.171.399.121.221.2]

OK

Figure 4.3.1. Microphone- SpeakerOption

File Mail Tools _Help

SystemOFF_(On]

?IX

f"

Auto Answer V EnableMail

-Numof

Rings-f _2rings

Modem _{[RockwellSoftK.56 Data,Fa:-:,Speakerph}

j^J r 4rings

Mic-Speaker [7 Default Record- Playback Device

F" Default

Answer IK DialPi:

SpeakerPhone Modem

File I Mic- Speaker Mdrn

Rem

Rec-PlaybackD ev

NanaU

ma

d

You

GameComDahbe Device

Game ComDatible Device Voice Modem Wave #01 Line GameCompatible Device Voice ModernWave tiOO Line Voice ModemWave ttOO Handset Sound System Playback₍₅₃₄₎

xjyL, i iruiil-i *i_u~^ _n.iJ

-s

010-_{Phone#1 Unknown Mes}

009-_PhoneSO,HookSwitchDevs Supported:

-Figure4.3.2. Wave Device Option

4. Turnonthe application(press "System OFF

(On)"

button).

5. Press "Dial Pad" button andthe application will be

launching

the "Login" _{pop up} window

(4.4. Dial Pad).

[image:21.589.142.441.260.527.2]

1Si, Dial Pad ^1^1 1 ?

|x|

1 2

5

8

0 3

i

ll800Marine1 k

enter_{destination phonevt|}

i 4 b Dial

7 9 Clear Dial_String

[image:22.589.224.395.95.237.2]

: Cancel

Figure 4.4. Dial Pad

6. Enterthedestinationphonenumber andpress

"Dial"

button.

IV.3.

Handle

an

Incoming

Call

If the "Enable Mail"

is unchecked, there are two ways the application can handle an

incoming

call(see attachment

"Incoming

Call Flow

Chart")

:

a.

Manually

: the "AutoAnswer"optionisunchecked

b.

Automatically

: the"AutoAnswer"

optionis checked.

IV.3.1.

Answer

an

Incoming

Call

Manually

Theuserdoesn't letthe application perform as _answeringmachine (itdoes not recordthe

caller's message). It means the user can

directly

handle an

incoming

call

by

_pressing "Answer"

buttonas showsinthe

following

steps :

1. Repeat step 1

- 4 in IV. 1

.

2. Ifthe caller calls

in,

the application will be ringing the user

(play

back

"Ringin.wav")

and

enable

"Answer"

button.

3. Press itandget connectedto thecaller.

4. Press

"Hang

Up"buttontoendthecall session.

IV.3.2. Answer

an

Incoming

Call

Automatically

The user lets the application perform as an _answering machine

by

_checking the "Auto

Answer"

option (Fig. 4.5. Auto Answer- Number

ofRings"). The application will playback the

greetingmessages and recordthecaller'smessage.

1. Repeat step 1

-4in TV. 1. 2. Checkthe "AutoAnswer"

checkbox.

3. Choose the number of rings (Fig. 4.5. Auto Answer Number of

Rings)

before the

application _{automatically}activate _answeringmachine(Toll Saver).

TAPI, MCI,RASAPI.MAPI andWinsocks

File Mail Tools Help

2aJH

(ISliiHEISH]

Modem

J7 Auto Answer

f-Enable Mail

~5

j

- _Num ofRings

-(* ₂rings

[image:23.589.146.444.187.268.2]

C 4rings

Figure 4.5. Auto Answer- Number

ofRings

4. Ifthe caller calls

in,

the application will playback an announcement

("greeting.wav")

to the

caller. Thistells the caller to press# 1 to

hang

_up the call or press # 2 to _{play back} message

afterthemessagelength (10

-thedefaultor35seconds)has beenelapsed(Fig. 4.6. Length of

theMessage).

TAPI. MCI.RASAPI.MAPIandWinsocks File

Sy

Modem

Tools Help

Set_Up

MsgLength ?! ? 10sees 35sees Rockw EnableMail

njx]

ax.Speakerph ?

]

NumofRings

( 2rings

C 4rings

Mic- Speaker f~

Default Record

-Playback Device |~"

Default

Figure 4.6. Lengthofthe Message

5. Theapplicationwillbe recordingthecaller's messagefor 10or35 seconds accordingly. 6. Save it the caller's message in the sane folder withthe application resides andname the file

with

"New_"

prefix follows

by

the date and time it was recorded (Fig. 4.7. Playback Message). [image:23.589.148.446.378.487.2]

Look in: S0fficialProject4

3

<S

|

gfr]

[ij"j

^Beeprnono

|?]Del_081

799-01 0031a

#J

greeting iJgreeting2

4}]

greeting23

ffil

greetings

iiNew 031 799-01 0529a

Filename: New 081 799-01 0529a Open

Filesoftype:

|

Wave File (".wav)

I-Openas_read-only

Cancel

4.7. PlaybackMessage

7. Playbackthesecond announcement("greeting2.wav").

8. Playbackthecaller's recorded message ifthecaller presses# 2.

9.

Hang

_upthecallsession ifthecaller presses# 1 or does onhook

IV.4.

Send

the

Caller's

Message to

an

Email

Address

If the "Auto Answer" and "Enable

Mail"

options are _checked, the application will

perform steps IV. 3. 2. and it also allows thecallerto send the messageto a predetermined email

address.

Afterthe callerpresses #

3,

the application will get _readyto sendthe caller's messageto

therecipientmail address. Before

firing

_up a_{dial up}connection (after 15 secondsthecaller

hang

up the connection),itwillcollectall connectioninformation inthe

"Login"

form fromtheuser.

Theuser can eitherselectNetscape Messenger orWindows Sockets asamailer(message

transport) to move out the message to the remote server. The mailer's default is Windows

Sockets. _{If using} the Netscape

Messenger,

the user must configure the Netscape Messenger.

Please click

"Instruction"

inthe "Help" menu(Fig. 4.8.

Help

Menu)

and will guideto dothat.

18-Si, TAPI, M CI, RAS API, MAPI andWinsocks

Hill

B

\

File Mail J_ools

|B|J

c nrr ,n

^Instructions

SystemOFF_(On)

About

-NumofRings i t* ₂rings

f"

Enable Mail 1

Modern

[Rockwell

_{SoftKSS Data,Fa:-:,Speakerph} [image:25.589.159.460.96.180.2]

j*j C 4rings

Figure 4.8.

Help

Menu

Theseare steps toenabletheapplication _sendingthecaller'smessage :

1. _{Repeat step 1} - 4

in IV.2. andcheck "Enable

Mail"

checkbox (Fig. 4.9. Enable Mail).

TAPI. MCI.RASAPI.MAPI andWinsocks

File Mail J_ools _Help

Six]

(SystemOF! F Auto Answer _R Enable Mail

Modem _{lockwell SoftK56 Data,Fa>}

,E . salerf

|

Figure4.9. Enable Mail

NumofRings

-( ₂rings

C 4rings

[image:25.589.163.460.273.352.2]

19-2. Theapplication will_{pop up}the "Login"window(Fig. 4.9.1. LoginWindow).

\Login

Mailer-C Netscape_Msg (* |W/indowsSockets;

^

User Name: _|Pyd0023

Password:

[

IfusingPBX, first dial digit

|

Phone Number 14272000

-DialAttemtps

C 2 Attempts {* 4Attemtps

Modem

Mail To

RIT2

"3

[email protected]

ServerName _{lvmsmaiLrit.edu}

From [email protected]

[image:26.589.192.371.125.421.2]

OK. Cancel

Figure 4.9.1.Login Window

3. Selectthemailer(Netscape MessengerorWindows Sockets

-the

default)

4. Entertheusername,password and phone numberto

log

ontoremote servername.

5. Enter the first digit the text box available if the application is connected to the PBX (Fig.

4.9.2. PBX Digit- Dial Attempts).

If_usingPBX, first dial digit (~~

Phone Number

I

toaccessanonline phonett,first

-DialAttemtps

C 2 Attempts (* _{4 Attemtps}

4.9.2. PBX Digit- Dial Attempts

6.

Specify

the maximum number oftones that the application will attemptto _{dial up} to get an

internet connection (Fig. 4.9.2. PBX Digit Dial Attempts). It would be performed if the

application (RAS

API)

failedtofire upaninternetconnectionto theremote server.

7.

Specify

amodemtobeusedto_{dial up}aninternetconnection

(Fig

4.9.3. ModemOption).

Modem

Mail To

Server Name _{lvmsmail.rit.edu}

[image:27.589.200.385.122.216.2]

From _{[email protected]}

Figure 4.9.3. Modem Option

8.

Specify

recipientmailaddress,remote server name and senderaddress.

Having

sent the message out, the application will _{automatically} terminate the internet

connection and get _ready to answer

incoming

calls or place _outgoing calls. _{If using Netscape}

Messenger,

theapplicationtakes around 80 seconds (after it got a_connection) to send amessage

out.

Theseare some actionsperformed

by

theapplication when

handling

an

incoming

call and followed

by

_sending the message to an email address (see attachment

"Incoming

Call Flow

Chart")

:

1. When user presses "System Off /

On"

button,

the application will initialize and open the

selectedmodem, setthenumber ofringsand setthe speaker phone on. 2. Ifthe"Auto Answer"and"Enable

Mail"

options arechecked, the applicationwill receive an

incoming

call after2 or4rings.

3. Thecaller willbepromptedto theannouncement_containingthree menus : Press #1 : to

hang

_upthecall.

Press #2 : tolistento thecaller's message.

Press #3 : tosendthemessagetotheemailaddress.

The application willcallcallGreeting(

)

functions inmdlTAPIFunc.bas

4. After_playing backthe_greetingmessageto the caller, the application starts_recordingcaller's

messagefor 10 or35 secondsbasedonuserselection.

The application will set _up the MCI device with the specific _recording audio i.e. standard

Windows wave file format

(PCM,

16 bitresolution with _sampling rate 8 kHz).

Finally

store

the recorded message to the specific file name based on the data and time it was recorded

(callMCIsaveMsg(

)).

5. If the user presses #

3,

the application will terminate the call session. Fifteen seconds after

thecall session was closed, the application will invoke Ras APIfunctions to establish a dial

upconnection.

6. _{After collecting} the connection information from the "Login"

dialog

box,

the

RasDial(

)

function tries to establish a _{dial up} connection to the remote server. Ifit

failed,

it redials _up

up to2or4attempts.

7. Ifthe application _successfully makes the _{dial up} connection, it starts

invoking

the Nestcape MessengerorWindowsSocketstosendthemessageout.

IftheuserselectstheWinsocks as_mailer,theapplicationwill performaconversionof

binary

format (attachment

file)

to ASCIItext (in module mdlMIME.bas). On the other

hand,

ifthe

user selects the Netscape Messenger

(MAPI),

the application will launch the Netscape and

doesn'tneedtoperform a

binary

formatconversion.

8. _{After successfully sending} the message, the application terminates the _{dial up} connection

(RasEnumEntries(

),

RasHangUp(

)).

9. And

finally

the application invokes

lineDrop(

),

lineDealloCall(

),

lineClose(

),

lineShutDown(

),

phoneclose(

)

and_{phoneShutDown(}

)

toclosethecall session.

IV.5.

Call Administrations

Theapplicationofferstheusertomanagethecaller's message andthe_greetingmessages

asfollows :

1. PlaybackaNew / Old Messageor

Greeting

Message

2. DeleteOld Messages

3. ChangetheAnnouncement

(Greeting Message)

IV.5.1. Playback

a

New

/ Old

Message

and

Greeting

Message

1. _{When starting} the application, it will

display

the new _message(s) to the user (Fig. 4.10.

Playback New / Old MessageandGreetings

-userhas 1 new_message)

2. Press "PlaybackMsg"button (Fig. 4.10.Playback New/ OldMessageandGreetings).

Youhave: 1 _NewMsg(s)

Playback_Msg

f""

I

r~

: :

I

[image:28.589.135.433.455.507.2]

Savebre Delete_Msg

Figure 4.10. PlaybackNew/ Old MessageandGreetings

3. The application will _{pop up} common

dialog

window so the user can select one of new

messagesto listento(4.7. Playback Message).

4. After the user is done to listen

it,

the application will rename the message file name to be "Del_"

prefixed file name (4.7. Playback Message). It will differentiate the new message

fromthemessagehas been listened.

22-IV.5.2. Delete Old Messages

1. Justpress

"Delete"

button. The application will deletealloldmessages

("Del_"

-prefixedfile name).

IV.5.3 Change

the

Announcement

(Greeting

Message)

The user could change the _greeting messages

("greeting.wav",

"greetings.wav",

"greeting2.wav",

"greeting23.wav").

1. Press VB's MCI record button to record user's _greeting (Fig. 4.11. Record

Greeting

Message).

You have: 0 _NewMsg(s)

:; Playback_Msg

?-

1

1 ₁

jG

Sit

h^

lultimediaControl Interface fete_Msa

1

[image:29.589.131.430.280.330.2]

| ₁

Figure 4.1 1. Record

Greeting

Message

2. Press "Save Greeting"

button to overwrite the old one and save it (Fig. 4.12. Overwrite and

Savethe

Greeting

Message).

Save As

OE3

Savejn:

1

13 0fficialProject31 _zl

HJ

&i

I^MJ

^Beepmono _<|JF^irigin

#|Del_081599-030657p

4|

greeting ^|f]greeting2

*|ygreeting23

4r]

greetings

Filename:

Saveastype:

|

Wave File_(K.wav)

f"

Openas_read-only

:

Save

3

Cancel

PlaybackMsg Delete_Msg

Figure 4.12. OverwriteandSavethe

Greeting

Message [image:29.589.139.445.408.640.2]

3. Playbackthenew _greetingmessageif it's necessary (press "Playback

Msg"

button).

24-V.

Telephony

Application

Programming

Interface

(TAPI)

The

Telephony

Application

Programming

Interface

(TAPI)

is one of the API sets to be

released

by

Microsoft. The TAPI is a single set of function calls that allows an application to

manage and manipulate _any type of communication link between the PC and the telephone line(s). An application that uses TAPI can generate a full set of

dialing

tones (answer an

incoming

call andplace an _{outgoing call)} and flash hookfunctions on /offhook (like that of

thesimple_{analog handset).}

TAPI defines severaldata structuresthat are usedto passinformation between TAPI and the _requesting application. The layout of the structures contains variable as well as fixed data

(seeatmdlTAPISource.bas module).

TAPI is sub into two subsets of API calls. Where each API subset (see at

mdlTAPISource.bas)refersto:

1. Line devices : a model of the physical

telephony

lines used to send and receive voice and

data between

locations,

such as fax

board,

a_modem, oranISDNcard.

2. Phone devices : amodel ofthe

desktop

handsetusedto placeandreceivecalls.

Two of the significant TAPI functions are HneCallBack and phoneCallBack function. These functions

keep

track _any state changes _occuring the telephone network and _notify the

application _accordingly

by

_sendinga_{corresponding}message(LINECALLSTATE).

V.l. Basic Typical TAPI Functions

These are theimportantsteps thatcanbeusedto receivea_call, place a_call, end a_call, close

the

line,

andleave TAPI (this condition _{is using} a non speakerphone _modem, so the application

doesn't need to call phone device functions such as _{phoneSetHookSwitch, phonelnitialize,}

phoneOpen) :

1.

Linelnitialize(

)

toopen aTAPIsessionbetweentheapplication andTAPIcalls.

2.

LineOpen(

)

toopen aspecificline devicetobe usedforthenextcall operations.

3.

LineSetNumRings(

)

tosetnumberofringsbefore an

incoming

callis answered'

4.

LineMakeCall( )

/

lineAnswer( )

toplace an_outgoingcall or_receivingan

incoming

call.

5.

LineMonitorDigits(

)

todetectdigits DTMFpressed

by

callers.

6.

LineDrop(

),

to placethe callin theIDLE state. The call still_exists, and the application still

hasits handle.

7.

LineDeallocateCall(

)

toreleasethecallhandle forthefinishedcall.Thecall nolongerexists.

8. Ifthe application expects no more calls on the

line,

ituses

lineClose(

)

to close the line. At thispoint,therewill beno more

incoming

or _outgoingcalls onthatline.

9.

LineShutdown(

)

toendtheuseofTAPI's functions forthecurrent session.

V.2.

Media

Stream

TAPI only provides control for line and phone devices and does not give access to the content ofthemedia streamthatconsistsoftheinformationexchangedovera call.

This application uses Win32 API

functions,

such as the Remote Access Service (RAS

API),

Media Control Interface

(MCI),

Messaging

Application

Programming

Interface

(MAPI)

or

Windows Sockets functions to manage themedia stream.

Although,

this application functions

like an _answering machine and send the recorded message through an email uses the TAPI functions to control and monitorthe an

incoming

_call, it uses the MCI functions to record and

savethemessage, RAS API functionstolaunchthe_{dial up}connectiontoremoteISP'sserverand then

finally

uses MAPI / Windows Sockets functions to transmit the actual data to an email address.

V.3. Data

Structure

(mdlTAPIFunction.bas,

_{mdlTAPISource.bas)}

Memory

forall datastructuresused

by

the APImustbe allocated

by

the application. The application passesa pointerto theAPI functionthatreturnsthe

information,

andthefunction fills

thedatastructure with therequestedinformation.

The defined data structures contain fields that indicate the total size neededto fill in all

variable data

(dwNeededSize)

_along with the total size used

by

TAPI when

filling

in the structure(dwUsedSize). Forexample :

Type VARSTRING

dwTotalSize As

Long

'size 4 byte dwNeededSize As

Long

'size 4 byte dwUsedSize As

Long

'size 4 byte dwStringFormat As

Long

'size 4byte dwStringSize As

Long

'size 4 byte dwStringOffset As

Long

'size 4byte End Type

Global Const VARSTRING_FIXEDSIZE = _{24 'total size needed}

by

this data structures

(4x6)

The dwTotalSizefield is firstset

by

the _callingapplication to indicatethe totalnumber of bytes allocatedfor TAPI to returnthe contents ofthe structure. If TAPIcannot fill in all values

without_running outofallocatedspace, anerrorisreturned.

Some TAPIfunctions inmdlTAPIFunction.bas module use particular data structures for

example :

lineOpen( )

incalllineOpen(

)

needsLINECALLPARAMS datastructure.

lineMakeCall( )

incalllineMakeCall(

)

needsLINECALLPARAMS datastructure.

V.4.

Initialize TAPI

(calllinelnitialize( ),

_{callphoneInotialize(}

)

-mdlTAPIFunction.bas)

Before placing or _receiving a _call, an application must establish communication link

between itselfandTAPI. The application must select a

telephony

event notification mechanism

(lineCallBack and_{phoneCallBack),} and _specify this in acall to the linelnitialize /phonelnitilize

function. One ofthe values linelnitialize /phonelnitialize returns is the number ofline / phone

devices available (lpNumLines /

lpNumPhones)

to the application. In_{this example, that} number

is one(if only onemodem

installed),

andtheline's ID in telephony'szero-based scheme is 0. The

application mustestablish this communication link (with

linelnitialize)

regardless ofthe type of

calltobeplaced orreceived.

V.5.

Monitor

Messages

from TAPI

(lineCallBack(

)

-mdlTAPILine.bas,

phoneCallBack(

)

-mdlTAPIPhone.bas)

The

LineCallBack( ) (mdlTAPILine.bas)

and _{phoneCallBack(}

)

(mdlTAPIPhone.bas)

functions are acallback schemethrough which applications are notified ofthesuccess or failure

offunctioncalls and other events. TAPIwillcontinuetoreceivestatusinformation androutethat

to the application through the callback function previously registered in

linelnitialize(

). The

qualityofthe status information

(dialing,

_ringing,

busy, idle,

and so _on) is all determined

by

the

hardware vendor and TAPI service provider application. The more sophisticated the

hardware,

themore accuratetheprogressinformation.

For _example, when the call session is

finished,

the application receives a

LINE_CALLS TATE message, which informs it that the state of a line device has changed. In

this example, a remotedisconnect has occurred. The application disconnects the call atthe local

end with

lineDrop

(on hook).

V.6. Open Line

/

Phone Devices

(calllineOpen( ),

callphoneOpen(

)

-mdlTAPIFunction.bas)

The function

lineOpen( )

and _phoneOpen(

)

will activate the specified line or phone device and give the application line (lphLine

)

/ phone

(lphPhone)

handle that be used for the

following

operationsonthe_{corresponding line /}phonedevice.

Once aline/phonedevice opened,theapplicationisenabletoplace an_outgoingcall or

receive an

incoming

call.

V.7.

Receive Calls

(calllineAnswer(

)

-mdlTAPIFunction.bas)

After an application has opened a line device

(calllineOpen( ))

registered a privilege

LtNECALLPRIVILEGE_OWNER

(allows the application to manipulate call), and a media mode

(LINEMEDIAMODE_AUTOMATEDVOICE

the call and the voice is

locally

handled

by

an automated_{application),}theapplicationisnotified when a call arrives onthatline.

Specifically,

an application that has opened the line with

LINECALLPRF/ILEGE.OWNER

receives a LINE_CALLS TATE message _{only if it} has

become an owner of the call. In this notification, TAPI gives the application a handle to the

incoming

call

(lineCallback( )

_{mdlTAPILine.bas),} and the application keeps this handle

(lhActiveCall)

untiltheapplicationdeallocatesthecall.

This handle will be used

by

lineAnswer

(calllineAnswer( ))

to receive an

incoming

call

when the application detects a message (LINEDEVSTATE_PJNGING

lineCallBack(

)

-mdlTAPILine.bas)sent

by

TAPI.

There are two conditions in this state. If "Auto Answer" is enabled the application will

automatically activate _{calllineAnswer(}

),

_{play back} an _{announcement,} and start _recording an

incoming

message. Ifnot, the user can _manually press

"Answer"

button toreceive an

incoming

call.

V.8. Monitor Digit DTMF

(calllineMonitorDigits(

)

-mdlTAPIFunction.bas)

The application will enable HneMonitorDigits when "Auto Answer" option is checked.

Detected DTMF digits cause the application to be notified with the LINE_MONITORDIGrTS

message

(HneCallBack(

)

mdlTAPILine.bas). This allows caller to press digit # 1 to

hang

_{up /}

disconnect_{the call,} pressdigit # 2 to _{play back} recorded message and press digit # 3 to send an e-mail.Digit monitoringon a call ends as soon asthecalldisconnects or goes idle.

The application disables this _{monitoring digits if} the user makes an _outgoing call or answers an

incoming

call.

V.9.

Place

the

Call

(calllineMakeCall(

)

-mdlTAPIFunction.bas)

Once the application has opened the line / phone

device,

it places the call with

lineMakeCall,

specifying the address in the IpszDestAddress parameter and the media mode

(LINEMEDIAMODE_AUTOMATEDVOICE)

in the lpCallParams parameter. This function

returnsapositive valueifthefunction willbecompleted _{successfully,} or a negative error number

if an error has occurred. Negative return values describe specific error states.

LINEERR_CALLUNAVAIL, forexample, means that the _{line is probably in} use (someone else

already has an active call). If

dialing

completes_{successfully,} messages are sentto the application

toinform it aboutthecall'sprogress.Oneofthemessageis

LINECALLSTATE_CONNECTED.

At the same _time, this application also calls _{callphoneSetHootSwitch(}

)

to set the hook

switchmode(offhookmode).

V.10. Set

Up

the

Phone Hook Switch

Mode

(callphoneSetHookSwitch(

)

-mdlTAPIFunction.bas)

The user can manipulate the phone hook switch mode to activate the speaker or microphone or both while

handling

an

incoming

or _outgoing call. The application will set

device's speaker on (mute themicrophone

PHONEHOOKSWITCHMODE_SPEAKER)

when

"Auto Answer"

is enabled. And it sets both devices active

(PHONEHOOKSWITCHMODE_MICSPEAKER

)

if the user places an _outgoing call or

manuallyanswers an

incoming

call

(pressing

"Answer"

button)

V.ll.

Toll Saver

(lineCallBack(

)

-mdlTAPILine.bas)

The application invokes lineGetNumRings functionto determinethe number oftimes an

inboundcall onthegiven address should _{ring before}the callis tobe answered.

Waiting

acertain

number of rings (2 or 4 _rings) allows callers to be spared the charge of a call connection.

Application also use the lineSetNumRings function in combination to provide a toll saver mechanism.

The application that receives a LINE_LINEDEVSTATE _ringing message should wait a

number of rings equalto thenumber returned

by

_{lineGetNumRings before answering}thecall.

The function lineGetNumRings returns the minimum number of rings _any application has

specifiedwiththefunction lineSetNumRings.

V.12.

Drop

the

Call

(caUlinedrop( )

-mdlTAPIFunction.bas)

To terminate a call, the application uses

lineDrop

on the call. This has the effect of

hanging

up on

(disconnecting)

the call, which makes itpossible tomake another call ontheline.

If the remote _{party disconnects} a _{call, the} local application receives a LINE_CALLSTATE

message via lineCallBack function

(mdlTAPILine.bas)

with a call state of disconnected

(LINECALLSATE_DISCONNECTED). If the local application disconnects a _call, the call

becomes idle (LINECALLSTATEJDLE), but its handle

(lhActiveCall)

is not _{automatically}

deallocated (the application must calllineDeallocateCall).

V.13. Deallocate Call Handles

(calllineDeallocCall( )

-mdlTAPIFunction.bas)

A call handle

(lhActiveCall)

remains valid after the call has been dropped. Once an

application has receivedaLINE_CALLSTATE

(LINECALLSTATEJDLE)

message, it should

call lineDeallocateCall to free system-allocated _memory related to the call. If an application is

theowner ofthe call,itcandeallocate thecall's handle only ifthecall is in the idlestate. Failure

to deallocate call handles in a

timely

_way can result in system failure and lost calls due to unnecessaryconsumptionof_memoryandother resources.

V.14.

Close Line / Phone Device

(calllineClose(

),

callphoneClose(

)

-mdlTAPIFunction.bas)

The application mustclose all lines /phonesit has openbefore it becomes inactive. After

an application _{is finished using} a line / phone

device,

it must close the device

by

_calling

lineClose( )

/_phoneClose(

)

on the line /phone -device handle. After theline /phone has been closed,the application'shandle fortheline /phone device isnolongervalid.

30-VI.

Multimedia Control Interface

(MCI)

As mentioned inproject _overview, themedia stream is the actual stream ofinformation

that travels on the line. Phone devices and calls on line devices are capable of_carrying media

streams. The Telephony-_{API line and phone device classes provide a wide range of control}

operations for these

devices,

but access to the media stream itself is not provided

by

TAPI.

Instead,

the application must use other APIs for the Win32 environments to access or manage

these media streams. One of these APIs includes the MCI (Media Control

Interface)

that

provides ahigh-levelgeneralized_{interface for controlling}mediadevices.

Forexample,for line

devices,

anapplication can useTAPItoanswer a connectionfrom a

caller. Once theconnectionis established,the application can thenusetheMCIWaveaudio API

on the associateddeviceto _{play back}

(send)

and record (receive

-and _save) audio dataover the

connection.

Thereare twoforms ofMCIcommandsets :

1. command strings (communicates using English like text,

such as : mmPlayMsgGree.Command=

"close",

mmPlayMsgGree.Command=

"open",

etc (seeat "PlayBackMsg" button in frmTAPLfrm).

2. command messages _{(communicates using} messages ID constants via _{mciSendCommand(}

)

functions and also additional parameters (data structures), such as : mciSendCommand

fnnTAPI.mmRecInMsg.DevicelD,

MCI_SAVE,

MCI_SAVE_FILE,

mcisaveparams _; see at

callMCISaveMsg(

)

in_{mdlTAPIFunction.bas)}

VI.l. MCI

Command Messages

An application will use _{mciSendCommand(}

)

functions and MCI command to send

messages that set _up and control multimedia devices (such as waveform _audio, a digital

sampling of an _analogsound source thatcanbe storedin afile and _{play back). Waveform} audio

provides amethodof_recordingand_{playing back}

digitally

sampled sound.

This application uses two MCI controls (mmPlayMsgGree and _mmRecInMsg) to _play

back a message andthe other one to record an

incoming

message. The basic strategy to record

andplayback waveformaudiois :

1. Locatethewaveform audiodevice.

Theuser must choose a suitable waveform audio _{recording / play back device in the}

"Choose Wave Device" combo box to be used to _{play back} and record waveform

audiooverto/ fromthephone connection.

The user must select modem wave device ("Voice Modem not local sound card

("Sound

Card")

inthatcombo

box,

otherwisetheWAV file will beplayedback over

thelocalsoundcardandtheapplication won'trecord an

incoming

message.

2. Openthewaveform audiodevice.

The application will open thatproper waveform audio _{device using} command _string (mmPlayMsgGree.Command =

"open"

or frmTAPI.mmRecInMsg.Command =

"open")

3. _{Call mciSendCommand(}

)

functionwith one oftheparametersbelow :

. MCI_SETtoset

recordingaudioformat

(PCM, 16-bit,

8

kHz,

mono).

-. MCI_RECORDto_{recorda message}based_on

recording audioformat.

-. MCI_STOP and MCI_SAVE to

stop recording process and then to save the

recordedmessageinaWAVfile format.

. MCI_PLAYtoplay backtherecorded messageoverthe telephoneline.

4. Close an open wave

device,

after a particular function finishes the particular task

(recording

and_{play back). So} thewavedevicecanbeusedforanotheropearation.

Besidesabove, themmPlayMsgGree - MCI

control allows userto record a new _greeting

(press record

button)

and overwrite theold one ("greeting.wav"). It alsoprovides userto access

all new or old

incoming

messages storedintheapplication'sfolder.

VI.2.

WAV Audio File

Format

To play backand record a message overthe telephone

line,

thisapplication_{using analog}

-digital conversion process (Pulse Code

Modulation)

_{using sampling} rates 8 kHz with digital

resolution 16-bitforonechannel(mono).

Audio recording based on this format would require 16 kB per second. Thus for 10 seconds wave

file,

the size wouldbe 160 KB and 35 seconds wave

file,

the size should be 560 kB. The highersample ratesthemorediskspaceis requiredto storethedigitalaudio.

VT.3.

Detecting

a

Proper

Recording

and

Playback Modem Wave

Device

(calllineGetID(

)

-mdlTAPIFunction.bas)

Toplayback_{(a greeting}orarecorded_message) andrecord (acaller's_message) to orfrom

the telephone

line,

the application will _{automatically detect} the proper modem wave device

by

invoking

lineGetID function (theapplication's default). This function will result a relateddevice

ID

being

used

by

the selected modem. The application will usethis ID to control modem wave

device insteadof_using an availablesound card.

When the user selects a sound card as a wave device

(by

_unchecking the default in the

check

box),

the_greetingorrecorded messages willbeplayedinthelocal soundcardnot overthe

telephoneline.

VI.4.

Recording

a

Message

(callMCIRecMsg(

)

-mdlTAPIFunction.bas)

To limit the length of each_recording so that one voicefile doesn't

inadvertently

take _up toomuchdisk _space,theapplicationuses Timercontrol

(Timerl)

to _specifytherecordtime. The

user can selectthe_recordingtimein "Mail". The maximum length ofthe voice file is 35 second

andthedefault is 10second.

Once the user specifies "Auto Answer" option is active and right after the application

playsback a_greetingto_{the caller,} itwill call_{callMCIRecMsg(}

)

to start_recording amessagefor

10or35 second.

This function will close an open wave device (MCI _control) first and then open it for

subsequent_recording operations.It willinvoke acommandmessage- MCI_SET

to set_recording audio format and also what voice modem (from the "Wave Device"

combo

box)

will be used

(parms.wlnput=

frmTAPI.cmbWaveRecord.Listlndex).

Finally

followed

by

theother command message- MCI_RECORD_to

recordthe

incoming

message.

Atthe same_time,thisfunction alsoactivates thetimercontrol(frmTAPI.Timerl.Enabled

=

True)

_to

keep

_{track the}length_{ofthemessage.}

VT.5.

Saving

a

Message

(callMCISaveMsg(

)

-mdlTAPIFunction.bas)

Once the Timer 1 has elapsed, the application will call _{callMCISaveMSG( )} to _stop the

recordingoperation

(MCI_STOP)

and store the recorded messageinapplication's folder. Before saving the recorded audio to the application's

folder,

it call

CreateFileName(

)

(mcisaveparams.lpFileName =

CreateFileName)

_to

specify the name of the file in which the

recordeddatawillbe stored.This filenamewillbenamedbasedonthedateandtimeitrecorded

("New_

& date &time&a/p.wav- 4.10. Overwrite

andSavethe

Greeting

Message).

Thisfunction alsobe_called, everytimethecaller

hang

_{up (press digit}

#1)

the connection

(seeat

lineCallBack( )

inmdlTAPILine.bas).

VT.6.

Playback

an

Announcement

-Greeting

(callGreeting( )

-mdlTAPIFunction.bas)

The application calls _{callGreeting(}

)

when "Auto Answer"

is chosen. It will do some

tasksbelow :

Close MCI device first andopenit (fanTAPI.mmPlayMsgGree.Command= "open").

Set data structure (Dim mciwavesetparms As

MCI_WAVE_SET_PARMS)

required before

applying command message MCI_PLAY. One of the significant parameters has to be provided is voice modem device where the message will be _play back to

(mciwavesetparms.wOutput=_{frmTAPI.cmbWaveRecord.Listlndex).}

Play

back greeting (after 2 or 4_rings) orrecorded message _{(caller pressing digit #}

2)

to the

caller.

Close MCIcontrol after_{playing back greeting}or recordedmessage done.

VI.7.

Detect

and

Display

MCI Error

Codes

(mdlTAPIMCI.bas)

Anapplicationhas todeterminethecontentofMCI_WAVE_SET_PARMS datastructure

before usingmciGetErrorString(

)

function todetect and

display

amessage. The length ofbuffer

to store theerror message returned

by

IpszErrorTextparameter is 300characters. To extract the

error message from series of

"0"

in the predetermined

buffer,

this function calls GetRidofO

(mdlTAPIPhone.bas)

toget rid of all0s fromthatbuffer.

VTI.

Remote Access Service Application

Programming

Interface

(RAS

API)

To allowthisapplicationtosendtherecorded message via an_{email, this} applicationmust

establish a connection to the remote ISP's server first before

invoking

a message transport

provider such as

Messaging

Application

Programming

Interface MAPI (Netscape

Messenger)

or

Windows Sockets tosenditout.

In Windows 95 environment, this can be done

by

use ofRemote Access Service (RAS

API)

that lets user to make a connection to the remote server without

launching "Dial-Up

Networking"

dialog

box up. This service also provide the _way to enumerate all active

connections first before

terminating

them.

ThemainRAS functionsusedinthisapplication are

(mdlTAPIRas.bas)

:

1.

RasEnumEntries( )

to enumerate and

display

the phone book entry available

by

which the

RasDial functionwillestablish aconnection or.

2.

RasDial( )

toestablishtheconnectionto theremote server.

3.

RasEnumConnections( )

toenumerate and

diplay

theactiveconnectionbefore

terminating

it.

4.

RasHangUp( )

toendtheactive connection.

VTI.l.

Starting

a

Connection

(callRasDial( )

-mdlRAS_API.bas)

Fifteen

(15)

seconds

(tmrcallDirectDialUp)

after the caller terminates a call, this

application will call RasEnumEntries function

(callRasEnumEntries(

)). The application must

wait 15 seconds or more to let the system to _properly close the _previously opened port. Ifthe

application performs

RasDial(

)

function less than 15 seconds the appli