Modem Connections: 2 Connecting

GEOS SDK TechDocs

1 Introduction

3 Sending Data

To establish a connection, MTalk does the following:

• allocates a buffer to be used (later) for holding received data
• prompts the user for the phone number to dial
• calls ModemConnect() (defined in modem.goc) to make the connection

Code Display 9-1 Making A Serial Line Connection

    /*
     * phoneNum - Phone number to dial.
     * retVal - Return value of ModemConnect().
     */
    char        phoneNum[MAX_PHONE_NUM_LENGTH + 1];
    Boolean     retVal;

    /*
     * Allocate a global memory block to be used as a buffer to hold received data.
     * A local buffer variable in the read function would use up
     * precious stack space, and a global buffer variable
     * would increase the size of the application's fixed data segment,
     * which degrades overall memory manager performance.
     *
     * Allocating it to be DISCARDABLE has further advantages.
     * Because we don't care what happens to the contents after they
     * have been processed, we'll allow the memory manager to throw
     * the block out if it decides it needs the heap space. This
     * means a little extra work for us whenever we want to use the
     * block, since we have to check for this condition, and
     * reallocate if necessary.
     */

    recvBuffer = MemAlloc( INPUT_BUFFER_SIZE, HF_DISCARDABLE, 0 );

    /*
     * If the buffer was not successfully allocated, memory must be getting low
     * so shut down.
     */
    if ( recvBuffer == NullHandle )
    {
	@send application::MSG_META_QUIT();
	return;
    }

    /*
     * Get the phone number to dial.
     */
    @call MTalkPhoneNumberText::MSG_VIS_TEXT_GET_ALL_PTR( phoneNum );

    /*
     * Create the modem connection and register the object and messages
     * it will receive when data is received or when the call has ended.
     * Note: in this example, oself refers to the process object.
     * Remember that ModemConnect() returns FALSE if it successfully makes
     * the connection.
     */
    retVal = ModemConnect( phoneNum,
			 oself,
			 MSG_MTALK_PROCESS_READ_DATA,
			 MSG_MTALK_PROCESS_CALL_ENDED );

    /*
     * If the connection failed, free the buffer and return. (Note: after freeing
     * any allocated memory, it is good practice to re-set handles and pointers to
     * Null so that you can test for a Null value later.)
     */
    if ( retVal )
    {
	MemFree( recvBuffer );
	recvBuffer = NullHandle;
	return;
    }

ModemConnect() takes care of the "housekeeping" details involved in making a connection. Specifically, this routine takes care of the following:

• checks to make sure the phone is available for use
• opens and configures the port (on the Nokia 9000i Communicator, the "virtual" serial port is COM1)
• initializes the modem
• sets up to receive notification when data arrives on the serial port or when the call ends
• dials the phone number

ModemConnect() takes four parameters:

phoneNumber

Char pointer to the phone number to dial.

dataReceiver

Optr to the object that will receive data or call end notification.

dataReceiptMessage

Message sent when data arrives on the port.

endCallMessage

Message sent when the call has ended.

ModemConnect() returns FALSE if the attempt to connect is successful. If the attempt is unsuccessful, it displays a dialog box notifying the user of the error. Possible error messages include:

"Connectivity Problem:

Data calls cannot be made while another call is active."

"Connectivity Problem: Line is busy. Try again later."

"Connectivity Problem:

No answer. Check the phone number and try again later."

"Connectivity Problem: General Error."

"Connectivity Problem: Error initializing modem."

GEOS SDK TechDocs

1 Introduction

3 Sending Data