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.
1 Introduction
1.1 General Remarks2 MDD Functions
1.2 Documentation Set
1.3 Declaration Files
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
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.
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:
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.CHAll MDD functions are used in one or more example programs.
NOTE: Constants defined for PowerBASIC (MDD32.PBI) begin with the character '%' symbol.
mddAttach(KeyCode)
KeyCode : (L) Registration key code.
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) {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
mddRelease.
mddBeginDial(Entry)
Entry : (I) Dialing entry number (0, 1, 2, etc.)
The mddBeginDial function begins the DUN dialing process for the specified dialing entry. Monitor the dialing status by calling mddDialStatus.
C/C++ Example
// dial using 1st entry (entry #0) Code = mddBeginDial(0);Visual Basic Example
' dial using 1st entry (entry #0) Code = mddBeginDial(0)
mddDialStatus
mddDebug(Index, Buffer, BufLen)
Index : (I) Command parameter (see below).
Buffer : (P) Buffer for results (string results only).
BufLen : (I) Size of above.
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); 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
None.
mddDialStatus()
The mddDialStatus function returns the current dialing status. Call mddBeginDial to initiate the dialing process.
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
mddBeginDial
mddErrorText(Code, Buffer, BufLen)
Code : (I) Error code.
Buffer : (P) Buffer to put text of error message into.
BufLen : (L) Size of above.
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
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
DIAL example program.
mddGetEntry(Entry, Buffer, BufLen)
Entry : (I) Entry number (0,1,2,...)
Buffer : (P) Buffer to put entry name into.
BufLen : (I) Size of above.
The mddGetEntry function gets the name of the specified dial entry, returning the size of the name copied into 'Buffer'.
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)
mddLoadEntries
mddHangup()
Nothing (void)
The mddHangup function hangs up the current DUN connection. Any Winsock programs executing using the DUN connection will be disconnected.
C/C++ Example
printf("Disconnecting.\n"); mddHangup();Visual Basic Example
Print "Disconnecting." Code = mddHangup()
mddBeginDial
mddLoadEntries()
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(); printf("%d available entries.\n", Code);Visual Basic Example
Code = mddLoadEntries() Print Str$(Code) + " available entries."
mddGetEntry
mddRelease()
The mddRelease function releases MDD. This should be the last MDD function called before exiting.
C/C++ Example
/* all done, release MDD */ printf("Releasing MDD.\n"); mddRelease();Visual Basic Example
' all done, release MDD Print "Releasing MDD." Code = mddRelease()
mddAttach
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.
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
// 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
mddBeginDial