MarshallSoft

MarshallSoft DUN Dialer
Library for Visual Basic


Programmer's Manual


(MDD4VB)


Version 2.1

June 13, 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 Visual Basic 4/5/6 Makefiles
2.2 Compiling VB 4/5/6 Programs
2.3 VB 5/6 MDD4VB Class
2.4 Compiling VB.Net Programs
2.5 Dynamic Strings
2.6 Key Code (License Key)
2.7 VB.Net
2.8 VBA Applications
3 VB 4/5/6 Example Programs
3.1 MDDVER
3.2 DIAL
3.3 CLASS
3.4 FLY
4 VB.NET Example Programs
4.1 MDDVER.VB
4.2 DIAL.VB
5 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.

Six example programs are included. See Sections 3.0 and 4.0 for details on each of the programs..

MDD4VB supports and has been tested with 32-bit Visual Basic compilers, including VB.Net.

MDD4VB can be used with Windows 95/98/Me/NT/2000/XP. The MDD4VB DLL (MDD32.DLL) can also be called 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.

The MDD_4VB 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_4VB 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

The following example code (for VB4/5/6) segment 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.

See mddver.vbproj for the equivalent VB.NET example program.

1.3 Installation

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

  2. Unzip MDD4VB21.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 MDD4VB files, including copying MDD32.DLL to your Windows directory. No Windows system files are modified.

  2. Load MDDVER32.MAK, compile and run.

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

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

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

2.1 Visual Basic 4/5/6 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 with 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 (VB4 to VB6), we use the Visual Basic makefile format. However, after loading, the examples can be saved in whatever format desired.

2.2 Compiling VB 4/5/6 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 and VB 6 users can save the project files in the VB 5 (or VB 6) format. When saving the example programs in VB 5 or VB 6 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 VB 5/6 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 VB 5 and VB 6 since previous versions of Visual Basic do not support classes.

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

2.4 Compiling VB.Net Programs

From the VB.Net menu, open VB/Net project files with "File/Open/Project". Note that VB.Net project files have the file extension ".vbproj".

Build the executable with "Build xxx", where xxx will be the name of the project file loaded.


2.5 Dynamic Strings

The Visual Basic language uses 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 (required if using VB.Net) that the local string be allocated immediately before use. For example, a string buffer is passed to a 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)
     ' function copies 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.6 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.BAS (VB 4/5/6) and in KEYCODE.VB (VB.Net). 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. Note that your keycode is NOT the same as your Customer ID/Registration ID.

2.7 VB.NET

There are a few difference between VB4/5/6 and VB.NET that affect writing programs that use MDD.

  1. Variables that are declared "As Long" in VB4/5/6 are declared "As Integer" in VB.NET.

  2. Fixed length strings are not supported in VB.NET. When calling any MDD function that can return a string (mddDebug, mddErrorText, mddGetEntry, and mddStatusText), memory for the string variable must be allocated first. For example:
     Buffer = Space(80) ' allocate memory for "Buffer"
     Code = mddStatusText(Status, Buffer, 80)


2.8 VBA Applications

MDD can be used with 32-bit Microsoft VBA (Visual Basic for Applications) applications such as EXCEL, ACCESS, and WORD. See the file VBA32.TXT for instructions on calling MDD functions from VBA applications.

3 VB 4/5/6 Example Programs

Several example programs are included in MDD4VB. Each VB4/5/6 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.6 " Key Codes" for more information on key codes.

Open the Visual Basic project 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 project makefile DIAL32.MAK.

3.3 CLASS

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

Open the Visual Basic 5/6 project file CLASS32.VBP.

3.4 FLY

The FLY example program operates like DIAL except that DUN parameters (user, password, and phone) are specified by the user at runtime.

At least one DUN entry must be previously installed on the computer. The FLY program inserts the specified parameters into DUN entry #0. After use, the original parameters for DUN entry #0 are restored.

Open the Visual Basic project makefile FLY32.MAK.



4 VB.NET Example Programs

There are two VB.Net specific example programs.

Be sure to read Section 2.7 "VB.Net" above.

4.1 MDDVER.VB

This is the VB.Net equivalent of the VB4/5/6 MDDVER program in Section 3.1 above. It displays the MDD version number, build number and registration string.

Open the VB.Net project file mddver.vbproj

4.2 DIAL.VB

This is the VB.Net equivalent of the VB4/5/6 DIAL program in Section 3.2 above. It dials up an ISP.

Open the VB.Net project file dial.vbproj


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

Version 2.0: January 19, 2001.

Version 2.1: June 13, 2002.