MarshallSoft DUN Dialer Library for Visual Basic


Programmer's Manual


(MDD4VB)


Version 1.0

June 9, 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.



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 Visual Basic Makefiles
2.2 Compiling Programs
2.3 MDD4VB Class
2.4 Dynamic Strings
2.5 Key Code
3 Example Programs
3.1 MDDVER
3.2 DIAL
3.3 CLASS
4 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.

See Section 3.0 for details on the example programs.

MDD4VB supports and has been tested with 32-bit Visual Basic compilers.

MDD4VB can be used with Windows 95/98, Windows NT/2000. The MDD4VB DLL (MDD32.DLL) can also be used from any Win32 application (C/C++, Delphi, etc.) capable of calling the Windows API.

When comparing MDD against our competition, note that:

  1. MDD4VB is a standard Windows DLL (NOT an OCX or ActiveX control) and is much smaller than a comparable OCX or ActiveX control.
  2. MDD4VB does NOT depend on ActiveX or Microsoft Foundation Class (MFC) libraries or similar "support" libraries.
  3. The MDD4VB 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 (MDD4VB) in the set.

Each manual comes in three formats:

1.2 Example Program

The following example code segmnet demonstrates the use of some of the library functions:


Private Sub mPushMe_Click()
Dim Code As Integer
Dim Version As Integer
Dim S1, S2, S3 As String
Dim Buffer As String * 81
' attach MDD
Code = mddAttach(MDD_KEY_CODE)
If Code < 0 Then
  MsgBox "ERROR: Cannot attach. Check MDD_KEY_CODE."
  End
End If
' 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
' get registration string
Code = mddDebug(MDD_GET_REGISTRATION, Buffer, 80)
Print Left$(Buffer, Code)
Print "Click [X] to exit"
Code = mddRelease()
End Sub

In the example program above, mddAttach is called to initialize MDD, and then mddDebug is called to get the version, build, and registration strings..

Lastly, mddRelease is called to perform MDD termination processing and release the Winsock.

1.3 Installation

  1. Before installation of MDD4VB, your 32-bit Visual Basic compiler should already be installed on your system and tested.

  2. Create your MDD4VB project directory, copy the MDD4VB archive, and then unzip the archive.

  3. Run INSTALL.BAT which will copy MDD32.DLL to either C:\WINDOWS or C:\WINNT.

  4. You're ready to run! The project files are:

Note that the Windows registry is not modified.

1.4 Uninstalling

Uninstalling MDD4VB is very easy. MDD does not modify the registry.

First, run UINSTALL.BAT, which will delete MDD32.DLL from your Windows directory, typically C:\WINDOWS for Windows 95/98 or C:\WINNT for Windows NT/2000.

Second, delete the MDD project directory created when installing MDD4VB.

1.5 Ordering

MDD4VB may be registered for $40. See the section "Ordering" in the MDD User’s Manual (MDD_USR) for details on ordering.

1.6 Updates

When you register MDD4VB 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.


2 Compiler Issues

2.1 Visual Basic Makefiles

The first Visual Basic for Windows (version 3.0) uses a text file known as a "Visual Basic makefile" (.MAK) to list all the file components necessary to compile a program. Beginning in version 4.0, the "Visual Basic Project file" (.VBP) was added. Both formats are "project files".

In order to allow our example programs to be compiled by all versions of Visual Basic, we use the Visual Basic makefile format. However, after loading, the examples can be saved in whatever format desired.

2.2 Compiling Programs

The example programs can be compiled from the Visual Basic development environment using the provided Visual Basic makefiles. Choose "File", then "Open Project" from the main VB menu.

The example program code is stored in Visual Basic MAK file formats, except for CLASS32, which is stored in Visual Basic VBP file format.

After opening a project, VB 5.0 (and above) users can save the project files in the VB 5.0 (or above) format. When saving the example programs in VB version 5.0 or VB 6.0 format, answer "no" if asked to add the "Microsoft DAO v2.5 library".

Compile and run MDDVER32 as the first example. MDDVER does not require a TCP/IP connection.

2.3 MDD4VB Class

The MDD class "mddClass" (mddClass.cls) is a Visual Basic class wrapper for making calls to MDD32.DLL. The class name for each function is the same as the DLL function, except the leading "mdd" is replaced by "f".

Those functions that return strings do so by use of the "String Result" property. Instantiate mddClass as any other class in Visual Basic:

Dim C As New mddClass

The use of mddClass is limited to Visual Basic 5.0 and above since previous versions of Visual Basic do not support classes.

Refer to the CLASS32 program for an example of using mddClass.

2.4 Dynamic Strings

The Visual Basic language use a technique known as "garbage collection" to manage string space at runtime, and may be called internally at any time by the Visual Basic runtime, asynchronous to what you may be doing in your code.

When passing a string buffer to a DLL function into which text will be copied, it is strongly recommended that the local string be allocated immediately before use. For example, a string buffer is passed to the dllGetMessage function, which copies a text message into it. Note that SPACE$(80) is called immediately before dllGetMessage.

   Dim Code As Integer
   Dim Buffer As String * 80
   ' allocate buffer just before call to dllGetMessage
   Buffer = SPACE$(80)
   ' copy message into 'Buffer'
   Code = dllGetMessage(Buffer, 80)
   ' message text is now in 'Buffer'

This technique is not necessary for passing a string to a DLL function, only when passing a buffer to a DLL into which data is to be placed by the DLL function.

2.5 Key Codes

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.BAS. 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 MDD32.DLL from the Windows search path.

3 Example Programs

Several example programs are included in MDD4VB. Each example program comes with either a Visual Basic makefile (MAK) or a Visual Basic Project (VBP) file.

Before writing your own programs, compile and run the example programs.

3.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 2.5 " Key Codes" for more information on key codes.

Use the following command line makefiles to compile MDDVER:

Open the Visual Basic makefile MDDVER32.MAK.

3.2 DIAL

The DIAL example program demonstrates how to use DUN (Dialup Networking) to dial up an ISP (Internet Service Provider). After starting DIAL, the first five DUN connections will be displayed.

Open the Visual Basic makefile DIAL32.MAK.

3.3 CLASS

The CLASS example program is identical to DIAL, except that is uses the Visual Basic class mddClass.cls. This requires Visual example Basic 5 or later, since earlier versions do not support classes.

Open the Visual Basic project file CLASS32.VBP.

4 Revision History

The MarshallSoft DUN Dialer (MDD32.DLL) is written in ANSI C. All language versions of MDD (C/C++, Delphi, Visual Basic, PowerBASIC, FoxPro, Delphi, Xbase++, dBase, COBOL) use the same MDD32.DLL.

Version 1.0: June 9, 2000.