MarshallSoft DUN Dialer

Reference Library


(MDD_REF)


Version 1.0

April 25, 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.

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 mddAttach: 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.

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


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.

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


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


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


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


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


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

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