MarshallSoft

MarshallSoft DUN Dialer
Library for C/C++


Programmer's Manual


(MDD4C)


Version 2.1

June 7, 2002



This software is provided as-is.
There are no warranties, expressed or implied.



Copyright (C) 2002
All rights reserved



MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815


Voice : 1.256.881.4630

FAX : 1.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 Documentation Set
1.2 Example Program
1.3 Installation
1.4 Uninstalling
1.5 Ordering
1.6 Updates
2 Compiler Issues
2.1 Command Line Tool Setup
2.1.1 Microsoft
2.1.2 Borland
2.1.3 Watcom
2.1.4 Lcc-Win32
2.2 Command Line Batch Files
2.3 Command Line Makefiles
2.4 Compiling Using an IDE
2.5 MDD C++ Class
3 Supported Compilers
3.1 Microsoft Visual C/C++
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 Compiling Example Programs
4.1 Static Libraries
4.2 Your Key Code (License Key)
5 Example Programs
5.1 MDDVER
5.2 DIAL
5.3 DMAN
5.4 DIAL_PRJ
5.5 FLY
5.6 WDIAL
5.7 HELLO
6 Revision History

1 Introduction

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.

Four example programs are included. See Section 5.0 for details on each of the 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/Me/NT/2000/XP. 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:

  1. MDD4C is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. MDD4C does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
  3. The MDD4C functions can be called from applications not capable of using controls.

1.1 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (MDD_4C) in the set.

The MDD_4C Programmer's Manual is the language specific manual. All language dependent programming issues are discussed in this manual. Read this manual first.

The MDD User's Manual (MDD_USR) discusses email processing as well as language independent programming issues. Read this manual after reading the MDD_4C Programmer's Manual.

The MDD Reference Manual (MDD_REF) contains details on each individual MDD function.

Each manual comes in three formats:

1.2 Example Program


   /*
   ** 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.DL 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.

1.3 Installation

  1. Before installation of MDD4C, your Windows C/C++ compiler should already be installed on your system and tested. In particular, include command line tools when installing your compiler if you want to compile using command line makefiles. If you need help with makefiles, see MAKEFILE.TXT.

  2. Unzip MDD4C21.ZIP (or MDDxxxx.ZIP where xxxx is your Customer ID) using PKUNZIP, WINZIP, or PKZIP for Windows.

  1. Run the WISE installation program SETUP.EXE which will install all MDD4C files, including copying MDD32.DLL to your Windows directory. No Windows system files are modified.

MDD requires RASAPI32.LIB. Microsoft VC (version 4.0 and up), Borland (version 5.0 and up), Watcom (version 11.0 and up), and Lcc-Win32 compilers provide this library.

1.4 Uninstalling

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/Me/XP or C:\WINNT for Windows NT/2000. That's it!

1.5 Ordering

See Section_1.4 of the MDD User's Manual (MDD_USR) for details on ordering.

1.6 Updates

When you register MDD 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, your license must be updated if you want to be able to download updates. Your license can be updated for $20 if ordered within one year from the original purchase (or previous update). After one year, licenses can be updated for $30.

Note that the registered DLL's never expire.


2 Compiler Issues

In order to compile from the command line, command line compiler tools must be set up properly.

2.1 Command Line Tool Setup

Your command line compiler tools must be set up properly. Note that you have an option of installing the command line tools (or not) when your compiler is first installed. Refer to your compiler manufacturer's manual for details.

If necessary, you can increase the size of your environment table space (to 1024 for example) by adding


     SHELL=C:\COMMAND.COM /e:1024 /p


to CONFIG.SYS in C:\ and then rebooting. Yes, this works for all versions of Windows, including Windows NT, 2000, and XP

For all compilers, your path should point to the compiler's BIN directory. For example, to add "C:\BC50\BIN" to your existing path, use

     PATH C:\BC50\BIN;%PATH%

2.1.1 Microsoft

Set LIB and INCLUDE environment variables. For example,

     SET INCLUDE=C:\MSVC\INCLUDE
     SET LIB=C:\MSVC\LIB

2.1.2 Borland

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. For example, assuming your BC compiler is installed at C:\BC5, the INCLUDE (-I) and LIB (-L) paths are specified by:


     -IC:\BC5\INCLUDE
     -LC:\BC5\LIB


BRCC (the Borland Resource Compiler) doesn't use the *.CFG files. Set the INCLUDE environment variable or BRCC will not be able to find the INCLUDE files (such as WINDOWS.H). For example,


     SET INCLUDE=C:\BC5\INCLUDE


Clear the LIB environment variable (so it is not present when SET is typed at the command line) with

     SET LIB=


2.1.3 Watcom

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

2.1.4 Lcc-Win32

The LCC environment variables are set like the others. For example,

     SET INCLUDE=C:\LCC\INCLUDE
     SET LIB=C:\LCC\LIB

After making the above changes for your compiler, type PATH at the command line prompt to verify the search path, and type SET at the command line prompt to verify the INCLUDE and LIB environment variables.


2.2 Command Line Batch Files

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.

2.3 Command Line Makefiles

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.

2.4 Compiling Using an IDE

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

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.

2.5 MDD C++ Class

Like Windows itself, MDD functions are coded in ANSI C, but they can be called directly from both ANSI C programs and from C++ programs.

MDD functions can also be called using the C++ class wrapper fmdd. Refer to the files fmdd.cpp and fmdd.h. See HELLO.CPP for an example.


3.0 Supported Compilers


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

3.1 Microsoft Visual C/C++

Microsoft Visual C/C++ programs can be compiled from either the command line or from within the Microsoft development environment

3.1.1 Microsoft Command Line Makefiles

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_

3.1.2 Microsoft Developer Studio

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

3.2 Borland C/C++

Borland C/C++ version 5.0 programs can be compiled from either the command line or from within the Borland development environment.

Borland C/C++ version 5.5 (which can be downloaded from www.borland.com) is a free Win32 console mode compiler (no IDE). Makefiles for BC 5.5 end with "._i_", and (like Borland C++ Builder) use ILINK32 rather than TLINK32. Be careful with linker response files (*.RSP) -- they must NOT end with a carriage return / line feed!

Borland programs always link with MDD32BCB.LIB.

3.2.1 Borland Command Line Makefiles

Programs can be compiled using command line makefiles.  All Borland 5.0 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 compile using the Borland 5.5 C/C++ compiler, use

     MAKE -f DIAL32._I_

3.2.2 Borland IDE

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:"

NOTE1: If, after linking in the IDE, you get unresolved external references to the library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above.

NOTE2: If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source".

The file DIAL32.IDE is a Borland C/C++ project file.

3.3 Borland Turbo C/C++ for Windows

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.


3.4 Borland C++ Builder

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.

3.5 Watcom C/C++

Watcom C/C++ programs can be compiled from either the command line or from within the Watcom development environment.

3.5.1 Watcom Command Line Makefiles

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_

3.5.2 Watcom IDE

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

3.6 Lcc-Win32 C/C++

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 msvcrt.lib mdd32lcc.lib -subsystem:console

4.0 Compiling Example Programs

4.1 Static Libraries

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:

  1. All application code that includes MDD.H must define STATIC_LIBRARY before including MDD.H
  2. Your application must link with WSOCK32.

If using Microsoft Developer Studio, make these changes:

  1. To your project file: Do NOT add MDD32.LIB to your project file.
  2. To the settings: (MDD "Build Settings" or "Project/Settings") (2a) C/C++ Tab: Add STATIC_LIBRARY to "preprocessor definitions:". (2b) Link Tab: Add WSOCK32.LIB and MDD32.OBJ to "object/library modules:". (2c) Link Tab: You may need to add RASAPI32.DLL and MSVCRT.LIB to "object/library modules:".

4.2 Key Codes (License Key)

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.


5 Example Programs

All of the example programs (except WDIAL & DIAL_PRJ) 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).

5.1 MDDVER

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:

MDDVER can also be compiled from Microsoft Visual C/C++ integrated environment:

5.2 DIAL

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:

5.3 DMAN

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:

5.4 DIAL_PRJ

The DIAL_PRJ example is a Borland C++ project file that dials using the DUN entry selected. The program requires Borland C++ Builder (any version).

5.5 FLY

The FLY example program is a console mode program that specifies the dialing parameters at runtime. For example, to dial 5551212 with user name "myuser" and password "qwerty", entry the following at the command prompt:

fly myuser qwerty 5551212

5.6 WDIAL

The WDIAL example program is similar to the DIAL console mode example, except that it is written in GUI mode.

WDIAL can also be compiled from Microsoft Visual C/C++ integrated environment:

5.7 HELLO

The HELLO C++ program is similar to MDDVER and demonstrates how to call the C++ class functions defined in fmdd.cpp.

HELLO can also be compiled from Microsoft Visual C/C++ integrated environment:

6 Revision History

Version 1.0: April 10, 2000.

Version 2.0: January 10, 2001.

Version 2.1: June 7, 2002.