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 mddSetParms
2.11 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.

Check http://www.marshallsoft.com for the latest version of our dialer software.

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.

• MDD Programmer's Manual (MDD_4x.DOC, MDD_4x.TXT, MDD_4x.HTM)
• MDD User's Manual (MDD_USR.DOC, MDD_USR.TXT, MDD_USR.HTM)
• MDD Reference Manual (MDD_REF.DOC, MDD_REF.TXT, MDD_REF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

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
     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

• Returns < 0 : Error code.
• Returns > 0 : No error.

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.

EXAMPLES

C/C++ Example

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

Visual Basic Example

    Code = mddAttach(MDD_KEY_CODE)
    If Code < 0 Then
      Print "ERROR: Code = " + Str$(Code)
      End
    End If

ALSO SEE

mddRelease.

2.2 mddBeginDial: Initiate DUN dialing.

SYNTAX

mddBeginDial(Entry)

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

RETURNS

• Returns < 0 : Error code.
• Returns > 0 : No error.

REMARKS

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

EXAMPLES

C/C++ Example

    // dial using 1st entry (entry #0)
    Code = mddBeginDial(0);

Visual Basic Example

    ' 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

• Returns < 0 : Error code
• Returns > 0 : Number of characters copied into 'Buffer'.

REMARKS

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

• MDD_GET_VERSION : Returns the current version number.
• MDD_GET_BUILD : Returns the current build number.
• MDD_GET_REGISTRATION : Returns the registration string.
• MDD_GET_DIALED_USER : Returns entry name.
• MDD_GET_DIALED_PASS : Returns password.
• MDD_GET_DIALED_PHONE : Returns phone dialed.

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.

EXAMPLES

C/C++ Example

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

Visual Basic Example

    ' get MDD version number
    Version = mddDebug(MDD_GET_VERSION, Buffer, 80)
    S1 = "MarshallSoft DUN Dialer Version "
    S2 = Hex$(Version)
    S3 = Mid$(S2, 1, 1) + "." + Mid$(S2, 2, 1) + "." + Mid$(S2, 3, 1)
    Print S1 + S3

ALSO SEE

None.

2.4 mddDialStatus: Get current dialing status.

SYNTAX

mddDialStatus()

RETURNS

• Returns < 0 : Error code.
• Returns > 0 : Dial status code.

REMARKS

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

EXAMPLES

C/C++ Example

    while(1)
      {/* get dialing status */
       Status = mddDialStatus();
       if(Status!=LastStatus)
         {LastStatus = Status;
          printf("Status is %d\n", Status);
          if( (LastStatus==MDD_IS_CONNECTED) ||
              (LastStatus==MDD_IS_DISCONNECTED) ||
              (LastStatus==MDD_IS_AUTHENTICATED)) break;
         }
      }

Visual Basic Example

    Do
      ' get dialing status '
      Status = mddDialStatus()
      If Status <> LastStatus Then
        LastStatus = Status
        Print "Status is % " +  Str$(Status)
        If (LastStatus=MDD_IS_CONNECTED) OR (LastStatus=MDD_IS_DISCONNECTED)
              OR (LastStatus=MDD_IS_AUTHENTICATED) Then
          Exit Do
        End if
      End if
    Loop

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

• Returns < 0 : Error code.
• Returns > 0 : Number of character copies into 'Buffer'.

REMARKS

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

EXAMPLES

C/C++ Example

    void ShowError(int ErrCode)
    {int Len;
     char Buffer[81];
     Len = mddErrorText(Code, (LPSTR)Buffer, 80);
     if(Len>0) printf("%s\n", Buffer);
     }

Visual Basic Example

    Private Sub ShowError(int ErrCode)
    Dim Len As Long
    Dim Buffer As String * 81
    Len = mddErrorText(ErrCode, Buffer, 80)
    If Len > 0 Then
      Print Left$(Buffer, Len)
    End If
    End Sub

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

• Returns < 0 : Error code
• Returns > 0 : Number of characters copies into 'Buffer'.

REMARKS

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

EXAMPLES

C/C++ Example

    char Buffer[128];

    // load 1st entry (# 0)
    Code = mddGetEntry(0, (LPSTR)Buffer, 128);

Visual Basic Example

    Dim Buffer As String * 128
    ' load 1st entry (# 0)
    Buffer = Space$(128)
    Code = mddGetEntry(0, Buffer, 128)

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.

EXAMPLES

C/C++ Example

    printf("Disconnecting.\n");
    mddHangup();

Visual Basic Example

    Print "Disconnecting."
    Code = mddHangup()

ALSO SEE

mddBeginDial

2.8 mddLoadEntries: Load all DUN dialing entries.

SYNTAX

mddLoadEntries()

RETURNS

• Returns < 0 : Error code
• Returns > 0 : The number of DUN entries.

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.

EXAMPLES

C/C++ Example

    Code = mddLoadEntries();
    printf("%d available entries.\n", Code);

Visual Basic Example

    Code = mddLoadEntries()
    Print Str$(Code) + " available entries."

ALSO SEE

mddGetEntry

2.9 mddRelease: Release MDD.

SYNTAX

mddRelease()

RETURNS

• Returns < 0 : Error code
• Returns > 0 : No error.

REMARKS

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

EXAMPLES

C/C++ Example

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

Visual Basic Example

    ' all done, release MDD
    Print "Releasing MDD."
    Code = mddRelease()

ALSO SEE

mddAttach

2.10 mddSetParms: Set dialing entry parameters.

SYNTAX

mddSetParms(User, Pass, Phone)

User  : (P) Buffer to put user name into.
Pass  : (P) Buffer to put user password into.
Phone : (P) Buffer to put phone number into.

RETURNS

• Returns < 0 : Error code

REMARKS

The mddSetParms function sets the user name, password, and phone number entries for the next call to mddBeginDial. This allows the user to specify the dialing parameters rather than use the entries that are already defined within DUN.

The changes made by calling mddSetParms are not permanent. The original values are replaced after the dial-up is completed.

See the FLY example program.

EXAMPLES

C/C++ Example

    char User[] = "myuser";
    char Pass[] = "qwerty";
    char Phone[] = "5551212";

    Code = mddSetParms(User, Pass, Phone);

Visual Basic Example

    Dim User As String
    Dim Pass As String
    Dim Phone As String
    ' set parms
    User = "myuser"
    Pass = "qwerty"
    Phone = "5551212"
    Code = mddSetParms(User, Pass, Phone);

ALSO SEE

mddLoadEntries

2.11 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

• Returns < 0 : Error code
• Returns > 0 : Number of characters copied into 'Buffer'.

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.

EXAMPLES

C/C++ Example

    // display 'Status' returned from mddDialStatus()
    Code = mddStatusText(Status,(LPSTR)Buffer, 128);
    if(Code>0) printf("Status %4d: %s\n", Status, Buffer);

Visual Basic Example

    ' display 'Status' returned from mddDialStatus()
    Code = mddStatusText(Status, Buffer, 128)
    If Code > 0 Then
      Print "Status " + Str$(Status) + " " + Buffer
    End If

ALSO SEE

mddBeginDial