MarshallSoft DUN Dialer

Reference Library


(MDD_REF)


Version 1.0

April 10, 2000




This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2000
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA



Voice : 256-881-4630

FAX : 256-880-0925

email : info@marshallsoft.com

web : www.marshallsoft.com


MarshallSoft is a member of the Association of Shareware Professionals

MARSHALLSOFT is a registered trademark of MarshallSoft Computing.


TABLE OF CONTENTS


1 Introduction
1.1 General Remarks
1.2 Documentation Set
1.3 Declaration Files
2 MDD Functions
2.1 mddAttach
2.2 mddBeginDial
2.3 mddDebug
2.4 mddDialStatus
2.5 mddErrorText
2.6 mddGetEntry
2.7 mddHangup
2.8 mddLoadEntries
2.9 mddRelease
2.10 mddStatusText


1. Introduction


1.1 General Remarks

All functions return an integer code. Negative values are always errors. Non-negative return codes are never errors.

Note that the mddErrorText function is used to get the text message associated with any error code.

Each function argument is marked as:

(I) : 4-byte integer
(L) : 4-byte integer
(P) : 4-byte pointer

Refer to the declaration files (see section 1.3 below) for the exact syntax of each MDD function. Also note that the example programs show exactly how MDD functions are called.


1.2 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the third manual (MDD_REF) in the set.

Each manual comes in three formats:


1.3 Declaration Files

The exact syntax for calling MDD functions are specific to the host language (C/C++, Delphi, VB, etc.) and are defined for each language in the "MDD declaration files". Each MDD product comes with the appropriate declaration file for the supported language. For example,

MDD4C       C/C++                   MDD.H
MDD4VB      Visual Basic                MDD32.BAS
            VBA (EXCEL,ACCESS,etc.) MDD32.BAS
MDD4PB      PowerBASIC              MDD32.BAS [not the same as above]
MDD4D       Borland Delphi          MDD32.PAS
MDD4CB      Fujitsu COBOL           MDD32.CBI
MDD4F       ABSOFT FORTRAN          MDD32.INC
MDD4FP      Visual FoxPro           MDD32.FOX
MDD4DB      Visual dBase            MDD32.CC
MDD4XB      Xbase++                 MDD32.CH
All MDD functions are used in one or more example programs.

NOTE: Constants defined for PowerBASIC (MDD32.PBI) begin with the character '%' symbol.



2 MDD Functions



2.1 mddAttach: Attach MarshallSoft DUN Dialer.

SYNTAX

mddAttach(KeyCode)

KeyCode : (L) Registration key code.

RETURNS


REMARKS

The mddAttach function initializes MDD32.DLL for subsequent use. The mddAttach function must be the first MDD call made.

When MDD is registered, you will receive a 'KeyCode' (8 to 10 digit number) which matches the 'KeyCode' within your registered DLL. For the shareware version, the keycode is 0. See file KEYCODE.

C/C++ EXAMPLE

Code = mddAttach(MDD_KEY_CODE);
if(Code<0)
   {if(Code==MDD_BAD_KEY_CODE) printf("%d is wrong key\n",MDD_KEY_CODE);
    else printf("ERROR: Code = %d\n", Code);
    exit(1);
   }

ALSO SEE

mddRelease.

2.2 mddBeginDial: Initiate DUN dialing.

SYNTAX

mddBeginDial(Entry)

Entry : (I) Dialing entry number (0, 1, 2, etc.)

RETURNS


REMARKS

The mddBeginDial function begins the DUN dialing process for the specified dialing entry. Monitor the dialing status by calling mddDialStatus.

C/C++ EXAMPLE

Code = mddLoadEntries();
if(Code<0)
  {printf("Error %d\n", Code);
   exit(1);
  }
printf("%d available entries.\n", Code);
// dial using 1st entry (entry #0)
Code = mddBeginDial(0);

ALSO SEE

mddDialStatus

2.3 mddDebug: Return debug information.

SYNTAX

mddDebug(Index, Buffer, BufLen)

Index : (I) Command parameter (see below).

Buffer : (P) Buffer for results (string results only).

BufLen : (I) Size of above.

RETURNS


REMARKS

The mddDebug function is used to return information from MDD32.DLL.

The 'Buffer' is not used for MDD_GET_VERSION and MDD_GET_BUILD. The version number returned (X.Y.Z) is formatted (in binary) as [0000|xxxx|yyyy|zzzz]. See the example below.

C/C++ EXAMPLE

Version = mddDebug(MDD_GET_VERSION,(LPSTR)Buffer,65);
Build = mddDebug(MDD_GET_BUILD,(LPSTR)Buffer,65);
printf("MDD32 Version: %1d.%1d.%1d Build %d\n",
   0x0f&(Version>>8),0x0f&(Version>>4),0x0f&Version,Build);
mddDebug(MDD_GET_REGISTRATION,(LPSTR)Buffer,65);
printf(" Registration: %s\n", Buffer);

ALSO SEE

None.

2.4 mddDialStatus: Get current dialing status.

SYNTAX

mddDialStatus()

RETURNS


REMARKS

The mddDialStatus function returns the current dialing status. Call mddBeginDial to initiate the dialing process.

C/C++ EXAMPLE

/* dial entry # 0 */
Code = mddBeginDial(0);
if(Code<0) . . .
while(1)
  {/* get dialing status */
   Status = mddDialStatus();
   if(Status<0) . . .
if(Status!=LastStatus)
   {LastStatus = Status;
      /* display status */
      Code = mddStatusText(Status,(LPSTR)Buffer, 128);
      if(Code>0) printf("Status %4d: %s\n", Status, Buffer);
      if( (LastStatus==MDD_IS_CONNECTED) ||
           (LastStatus==MDD_IS_DISCONNECTED) ||
           (LastStatus==MDD_IS_AUTHENICATED)
         ) break;
     }
   Sleep(1000);
  }

ALSO SEE

mddBeginDial

2.5 mddErrorText: Get text associated with error code.

SYNTAX

mddErrorText(Code, Buffer, BufLen)

Code : (I) Error code.

Buffer : (P) Buffer to put text of error message into.

BufLen : (L) Size of above.

RETURNS


REMARKS

The mddErrorText function gets the text of an error message associated with the error returned by a previous call to a MDD function.

C/C++ EXAMPLE


Code = mddLoadEntries();
if(Code<0)
  {int Len;
   char Buffer[128];
   Len = mddErrorText(Code, (LPSTR)Buffer, 128);
   if(Len>0) printf("ERROR %d: %s\n", Code, Buffer);
  }

ALSO SEE

DIAL example program.



2.6 mddGetEntry: Retrieve dialing entry name.

SYNTAX

mddGetEntry(Entry, Buffer, BufLen)

Entry : (I) Entry number (0,1,2,...)

Buffer : (P) Buffer to put entry name into.

BufLen : (I) Size of above.

RETURNS


REMARKS

The mddGetEntry function gets the name of the specified dial entry, returning the size of the name copied into 'Buffer'.

C/C++ EXAMPLE

/* load all dial entries */
Code = mddLoadEntries();
if(Code<0) . . .
printf("%d available entries.\n", Code);
/* list all dialing entries */
NbrEntries = Code;
for(i=0;i<NbrEntries;i++)
  {Buffer[0] = '\0';
   Code = mddGetEntry(i, (LPSTR)Buffer, 128);
   if(Code<0) . . .
   printf("%d [%s]\n", i, Buffer);
  }

ALSO SEE

mddLoadEntries

2.7 void mddHangup: Hang up DUN connection.

SYNTAX

mddHangup()

RETURNS

Nothing (void)

REMARKS

The mddHangup function hangs up the current DUN connection. Any Winsock programs executing using the DUN connection will be disconnected.

C/C++ EXAMPLE

/* all done, release MDD */
printf("Disconnecting.\n");
mddHangup();
mddRelease();

ALSO SEE

mddBeginDial

2.8 mddLoadEntries: Load all DUN dialing entries.

SYNTAX

mddLoadEntries()

RETURNS


REMARKS

The mddLoadEntries function loads all DUN entries installed on the computer. After calling this function, the name of each DUN entry can be specified by calling mddGetEntry.

C/C++ EXAMPLE

Code = mddLoadEntries();
if(Code<0)
  {printf("Error %d\n", Code);
   exit(1);
  }
printf("%d available entries.\n", Code);

ALSO SEE

mddGetEntry

2.9 mddRelease: Release MDD.

SYNTAX

mddRelease()

RETURNS


REMARKS

The mddRelease function releases MDD. This should be the last MDD function called before exiting.

C/C++ EXAMPLE

/* all done, release MDD */
printf("Disconnecting.\n");
mddHangup();
mddRelease();

ALSO SEE

mddAttach

2.10 mddStatusText: Get text associated with status code.

SYNTAX

mddStatusText(Status, Buffer, BufLen)

Status : (I) Status code as returned by mddDialStatus.

Buffer : (P) Buffer to put text of status message into.

BufLen : (I) Size of above buffer.

RETURNS


REMARKS

The mddStatusText function is used to get the text of the status message associated with a status code returned by mddDialStatus.

See the example below.

C/C++ EXAMPLE

Code = mddBeginDial(0);
if(Code<0) . . .
while(1)
  {/* get dialing status */
   Status = mddDialStatus();
   if(Status<0) . . .
   if(Status!=LastStatus)
     {LastStatus = Status;
      /* display status */
      Code = mddStatusText(Status,(LPSTR)Buffer, 128);
      if(Code>0) printf("Status %4d: %s\n", Status, Buffer);
      if( (LastStatus==MDD_IS_CONNECTED) ||
           (LastStatus==MDD_IS_DISCONNECTED) ||
           (LastStatus==MDD_IS_AUTHENICATED)
         ) break;
     }
   Sleep(1000);
  }

ALSO SEE

mddBeginDial