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.

o MDD4x Programmers Manual (MDD4x.DOC, MDD4x.TXT, MDD4x.HTM) 
o MDD Users Manual (MDD_USR.DOC, MDD_USR.TXT, MDD_USR.HTM) 
o MDD Reference Manual (MDD_REF.DOC, MDD_REF.TXT, MDD_REF.HTM) 

Each manual comes in three formats:

o Microsoft Word (files ending in .DOC). The best format for printing manuals. 
o Hyper Text (files ending in .HTM). Use any web browser to read. 
o 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
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

o Returns < 0 : Error code. 
o 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

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

ALSO SEE

mddRelease.


2.2   mddBeginDial:  Initiate DUN dialing.

SYNTAX

mddBeginDial(Entry)

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

RETURNS

o Returns < 0 : Error code. 
o 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

_begin_code
' dial using 1st entry (entry #0)
Code = mddBeginDial(0)
_end_code

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

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

REMARKS

The mddDebug function is used to return information from MDD32.DLL.
 
o MDD_GET_VERSION : Returns the current version number. 
o MDD_GET_BUILD : Returns the current build number. 
o MDD_GET_REGISTRATION : Returns the registration string. 

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

_begin_code
' 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
_end_code

ALSO SEE

None.


2.4   mddDialStatus:  Get current dialing status.

SYNTAX

mddDialStatus()

RETURNS

o Returns < 0 : Error code. 
o 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_AUTHENICATED)) break;
     }
  }

Visual Basic Example

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

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

o Returns < 0 : Error code. 
o 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

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

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

o Returns < 0 : Error code 
o 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

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

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

_begin_code
Print "Disconnecting."
Code = mddHangup()
_end_code

ALSO SEE

mddBeginDial


2.8   mddLoadEntries:  Load all DUN dialing entries.

SYNTAX

mddLoadEntries()

RETURNS

o Returns < 0 : Error code 
o 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

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

ALSO SEE

mddGetEntry 


2.9   mddRelease:  Release MDD.

SYNTAX

mddRelease()

RETURNS

o Returns < 0 : Error code 
o 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

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

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

o Returns < 0 : Error code 
o 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

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

ALSO SEE

mddBeginDial

