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.
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.
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); }
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.
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);
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.
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);
mddDialStatus()
The mddDialStatus function returns the current dialing status. Call mddBeginDial to initiate the dialing process.
/* 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); }
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.
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); }
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'.
/* 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); }
mddHangup()
Nothing (void)
The mddHangup function hangs up the current DUN connection. Any Winsock programs executing using the DUN connection will be disconnected.
/* all done, release MDD */ printf("Disconnecting.\n"); mddHangup(); mddRelease();
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.
Code = mddLoadEntries(); if(Code<0) {printf("Error %d\n", Code); exit(1); } printf("%d available entries.\n", Code);
mddRelease()
The mddRelease function releases MDD. This should be the last MDD function called before exiting.
/* all done, release MDD */ printf("Disconnecting.\n"); mddHangup(); mddRelease();
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.
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); }