MarshallSoft DUN Dialer
Library for C/C++
Programmer's Manual
(MDD4C)
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
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 Documentation Set2 Compiler Issues
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2.1 Command Line Tool Setup3 Supported Compilers
2.1.1 Microsoft2.2 Command Line Batch Files
2.1.2 Borland
2.1.3 Watcom
2.1.4 Lcc-Win32
2.3 Command Line Makefiles
2.4 Compiling Using an IDE
3.1 Microsoft Visual C/C++4 Compiling Example Programs
3.2 Borland C/C++
3.3 Turbo C/C++ for Windows
3.4 Borland C++ Builder
3.5 Watcom C/C++
3.6 Lcc-Win32 C/C++
4.1 Static Libraries5 Example Programs
4.2 Your Key Code
5.1 MDDVER6 Revision History
5.2 DIAL
5.3 DMAN
5.4 DIAL_PRJ
The MarshallSoft DUN Dialer (MDD) is a library of functions that allows your Win32 application program to dial up a local ISP (Internet Service Provider) using any existing DUN (Dialup Network) connection.
See Section 5.0 for details on the four example programs.
MDD4C supports and has been tested with Microsoft Visual C/C++, Borland C/C++, Turbo C/C++ for Windows, Borland C++ Builder, Watcom C/C++, and Lcc-Win32 compilers. It can also be used with most other C/C++ Windows compilers.
MDD4C can be used with Windows 95/98, Windows NT, and Windows 2000. The MDD4C DLL (MDD32.DLL) can also be used from any Win32 application (Visual Basic, Delphi, etc.) capable of calling the Windows API.
When comparing MDD against our competition, note that:
The complete set of documentation consists of three manuals in three formats. This is the first manual
(MDD4C) in the set.
Each manual comes in three formats:
/* Displays MDD32.DLL version, build, and registration string. */ #include <windows.h> #include <stdio.h> #include "mdd.h" #include "keycode.h" static char Buffer[65]; void main(void) {int Code; int Version; int Build; /* attach MDD */ 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); } 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); mddRelease(); }
The above program attaches MDD32.DLL, and displays the version number, build number, and
registration string. This is always the first program to run in order to verify that you
can make calls to the
DLL.
The registration string will be "SHAREWARE VERSION [www.marshallsoft.com]". After a customer registers MDD4C, the registration string will be changed to one that identifies the purchaser.
The INSTALL batch file will copy MDD32.DLL to your Windows directory. All recent Win32 C/C++ compilers support the "declspec" keyword. Microsoft VC (version 4.0 and up), Borland (version 5.0 and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers support the "declspec" keyword.
We also have DLLs that can be used with older Borland and Watcom Windows compiler. Contact us if you want to use one of these older compilers with MDD4C.
Uninstalling MDD4C is very easy. MDD does NOT modify the registry. First, delete the MDD project directory created when installing MDD4C. Second, delete MDD32.DLL from your Windows directory; typically C:\WINDOWS for Windows 95/98 or C:\WINNT for Windows NT. That's it!
The registration cost for MDD4C is $40. See Section 1.5 of the MDD User’s Manual (MDD_USR) for details on ordering.
When you register MDD4C you will receive a set of registered DLLs plus a license file
(MDDxxxx.LIC)
that can be used to update your registered DLL’s for a period of one year from purchase.
Updates can be
downloaded from
http://www.marshallsoft.com/oem.htm
After one year, licenses can be updated for $20 for email delivery.
In order to compile from the command line, command line compiler tools must be set up properly.
For all compilers, your path should point to the compiler BIN directory. For example, to add "C:\BC50\BIN" to your existing path, use
PATH C:\BC50\BIN;%PATH%
Set LIB and INCLUDE environment variables. For example,
SET INCLUDE=C:\MSVC\INCLUDE
SET LIB=C:\MSVC\LIB
Check that TURBOC.CFG, BCC32.CFG, TLINK.CFG, and TLINK32.CFG all have the correct information in them, as they should have when your compiler was installed.
Set the INCLUDE environment variables. For example,
SET INCLUDE=C:\BC50\INCLUDE
BRCC doesn't use any *.CFG files, but will use INCLUDE if set as above.
If "SET LIB=" is used, it must point to Borland’s LIB directory. Assuming that TURBOC.CFG is correct, it is best to clear the LIB environment variable with
SET LIB=
Set the WATCOM environment variables to point to your compilers include (H) and BIN directories. For example,
SET INCLUDE=C:\WC11\H;C:\WC11\H\NT
SET WATCOM=C:\WC11
SET EDPATH=C:\WC11\EDDAT
SET WWINHELP=E:\BINW
The LCC environment variables are set like the others. For example,
SET INCLUDE=C:\LCC\INCLUDE
SET LIB=C:\LCC\LIB
If your compiler installation includes command line tools, then all of the example programs can be compiled directly from the command line. These same compiler commands can also be placed in a batch file.
See DIAL32.BAT for an example of a console mode command line batch file. Command line batch files can be created for all example programs using a command line compiler.
Command line makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. The advantage of makefiles (as compared to an integrated development environment) is that all compiler switches are coded within the makefile and the makefile can be run with a single keystroke.
Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers.
All current windows compilers have an "Integrated Development Environment" (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard.
Note that not only do IDE's vary between the different compiler manufacturers, but they also vary from version to version for the same compiler.
Creating a project makefile for the examples that have only command line makefiles is fairly straight forward. All of the IDE's use the concept of a file hierarchy. For example, the DIAL example program file hierarchy in the IDE (for 32-bit) should look like:
DIAL.EXE
+++ DIAL.C
+++ MDD32.LIB
Replace MDD32.LIB above with MDD32BCB.LIB if using Borland C++ Builder, and with MDD32LCC.LIB if using Lcc-Win32.
The order of the files is not significant. Also refer to the sections on individual IDE's that follow this section.
MDD4C has been tested with Microsoft Visual C/C++, Borland C/C++ , Borland C++ Builder, Borland Turbo C/C++, Watcom C/C++, and Lcc-Win32. Other Windows C/C++ compilers may work as well.
We recommend Microsoft Visual C/C++ version 4 or above, Borland C/C++ (version 5 and above), Borland C++ Builder (any version) , Watcom C/C++ (version 11 and above), and Win-Lcc (version 4-10- 1998 and above).
Microsoft Visual C/C++ programs can be compiled from either the command line or from within the Microsoft development environment. All MSVC programs are Win32 only.
Programs can be compiled using command line makefiles. All Microsoft Win32 command line makefiles end with "32._m_". To compile using a makefile, use the Microsoft NMAKE utility. For example,
NMAKE -f DIAL32._M_
To open an existing project, choose "File", then "Open Workspace", and then select "Makefiles" from the list of file types. Several of the example programs have Microsoft Visual Studio C/C++ makefiles, ending with ".MAK" , such as
DIAL32.MAK
To create a new project in MSVC 4.0, choose "File", then "New", then "Project Workspace". Select "Application" or "Console Application" for "Type:" and your project name for "Name:". Choose Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames including any resource file (.RC) and MDD32.LIB. Lastly, select "Build", then "Rebuild All".
To create a new project in MSVC 5.0, choose "File", then "New", then "Win32 Application" or "Win32 Console Application " and your project name. Check "Create new workspace. Select "Project", then "Add to Project". Add all filenames including any resource file (.RC) and MDD32.LIB. Lastly, select "Rebuild All".
Creating a new project in MSVC 6.0 follows the same logic as for MSVC 5.0.
Borland C/C++ programs can be compiled from either the command line or from within the Borland development environment.
In order to use MDD with Borland C/C++ version 5.0 or later, install using "INSTALL U". To use with Borland version 4.0 or 4.5, install with "INSTALL B".
Programs can be compiled using command line makefiles. All Borland Win32 command line makefiles end with ’32._b_". To compile using a makefile, use the Borland MAKE utility. For example,
MAKE -f DIAL32._B_
To create a new project, first turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes.
Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "GUI" or "Console" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:"
The file DIAL32.IDE is a Borland C/C++ project file.
Borland Turbo C/C++ for Windows does not have command line tools, so all programs must be compiled from the Turbo C/C++ integrated environment.
Follow the same directions as above (Borland IDE), except that the "Target Model:" can be any listed.
Borland C++ Builder does not have command line tools, so all programs must be compiled from the Borland C++ Builder integrated environment. Compile the BCB example program QM_PRJ with QM_PRJ.MAK if running BCB version 1 through 3, and compile with QM_PRJ.BPR if running BCB version 4 or above.
To load the QM_PRJ example project, Choose "File" / "Open Project" on the menu bar. Load QM_PRJ.MAK (or QM_PRJ.BPR). Then, choose "Build All" from "Project" to create the executable. Note that MDD32BCB.LIB is the LIB file used with Borland C++ Builder.
Watcom C/C++ programs can be compiled from either the command line or from within the Watcom development environment.
All Watcom command line makefiles end with "32._w_" for Win32 makefiles. To compile using a makefile, use the Watcom WMAKE utility. For example,
WMAKE -f DIAL32._W_
To create a new project, choose "File", then "New Project". Enter the project name and then choose Win32 as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered.
Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]".
Lcc-Win32 C/C++ programs can be compiled from either the command line or from within the development environment.
Lcc-Win32 is a freeware C compiler developed and distributed by Jacob Navia at
http://www.geocities.com/SiliconValley/Heights/9069/index.html
To use our DLLs with Lcc-Win32, you must link with MDD32LCC.LIB. This file can also be re-created using the Lcc-Win32 utility BUILDLIB.
buildlib MDD32.lcc MDD32lcc.lib
Then, compile and link as normal. For example, to compile the DIAL console mode example program:
lcc -DWIN32 dial.c
lcclnk dial.obj MDD32.lib -subsystem:console
The registered user can also statically link MDD32.OBJ rather than making calls to the
DLL's.
To create an application which links MDD32.OBJ statically:
If using Microsoft Developer Studio, make these changes:
MDD32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the shareware version is 0. You will receive a new key code when registering.
If you get an error message (value -74) when calling mddAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the shareware version of the MDD DLL's from the Windows search path.
Most of the example programs are written in Win32 console mode. This was done in order to provide the clearest possible code, without the complication and complexity of GUI code. All console mode programs can be converted to GUI mode by coding the necessary Windows code.
The first example program, MDDVER, displays the MDD library version number and registration string. From the command line, type:
MDDVER
MDDVER can be compiled from either the command line or from Microsoft Visual Studio (MDDVER32.MAK).
The MDDVER (MDD Version) program should be the first example program that you compile and run. It displays the MDD version, build, and registration string. If you get the error "…wrong key", then you are not passing the correct keycode to mddAttach. Refer to Section 4.2 "Your Key Code" for more information.
Use the following command line makefiles to compile MDDVER:
The DIAL example program is a Win32 console mode program that shows how to use DUN (Dialup Networking) to dial up an ISP (Internet Service Provider).
Use the following command line makefiles to compile DIAL:
DIAL may also be compiled from the compilers integrated development environment:
The DMAN program is a Win32 console mode program that controls Dialup Networking (DUN), depending on the contents of a CONTROL subdirectory.
Create a subdirectory named CONTROL, but do NOT change to the subdirectory. That is, do NOT do a "cd control".
Start DMAN. Once DMAN starts, it will write a file named ENTRIES.OUT which contains a list of all DUN entries. They are numbered starting from 0.
To have DMAN dial, first create a file named DIAL.CMD and put the number of the entry to dial into it. For example, to dial the first dial entry, put a 0 inside DIAL.CMD. See the DIAL.CMD file included in the archive. Then, copy DIAL.CMD to the CONTROL directory. Within a few seconds, DMAN should begin dialing.
Once connected, the file STATUS.OUT will be created in the control directory, containing the last status returned by DUN.
To hang-up, copy HANGUP.CMD to the control directory. To terminate DMAN, copy EXIT.CMD to the control directory.
DMAN is controlled totally by files written to the control directory. This means that it can be controlled by any application program (Win16, Win32, or DOS) that is capable of creating files.
Use the following command line makefiles to compile DMAN:
The DIAL_PRJ example is a Borland C++ project file that dials using the DUN entry
selected. The
program requires any version of Borland C++ Builder.
Version 1.0: April 10, 2000.
The official release of version 1.0.