The RasDialParams structure is used in the RasDial function to specify the entry to dial. The structure can also specify parameters to use such as the username and/or password to use, the phone number to dial etc. When using the RasDial function, you can use the RasGetEntryDialParams function to retrieve the password and username for the entry.
We can also set/retrieve the dialling parameters for an entry by using the RasSetEntryDialParams and RasGetEntryDialParams functions.
From the platform SDK the structure looks like this:
typedef struct _RASDIALPARAMS {
DWORD dwSize;
TCHAR szEntryName[RAS_MaxEntryName + 1];
TCHAR szPhoneNumber[RAS_MaxPhoneNumber + 1];
TCHAR szCallbackNumber[RAS_MaxCallbackNumber + 1];
TCHAR szUserName[UNLEN + 1];
TCHAR szPassword[PWLEN + 1];
TCHAR szDomain[DNLEN + 1] ;
#if (WINVER >= 0x401)
DWORD dwSubEntry;
ULONG_PTR dwCallbackId;
#endif
} RASDIALPARAMS;
Note: the structure has two extra properties for windows NT4 enhanced and Windows 2000. Also the RAS_MaxEntryName constant is different for NT3.5. This gives us a 3 different possible sizes for the RasDialParams structure, being 1060, 1052, and 816 bytes.
To determine the appropiate size for the RasDialParams structure, we can call the RasGetEntryDialParams function and try each of the three sizes, starting with the largest (newest) and going towards the smallest size. The RasGetEntryDialParams function will return a value of 632 (ERROR_INVALID_SIZE) or 610 (ERROR_BUFFER_INVALID) if we have specified the wrong value in the first four bytes of our RasDialParams structure.
The following function, VBRasGetEntryDialParams, get's the dialling parameters for a given entry as a byte array (bytesOut()). You can use this byte array with the RasDial function. The function also returns a long value equivalent to a Ras error code. If the operation is successful the value should be 0, else use the VBRasErrorHandler function to get it's description.
To use this function, call it like so:
Dim b() as byte
Dim rtn as Long
rtn = VBRasGetEntryDialParams(b, vbNullString, "MyConnection")
Note: on NT or later you can also specify the phonebook. On win 95/98 the phonebook parameter is ignored.
The declares and helper functions are at the end of this page.
Function VBRasGetEntryDialParams _
(bytesOut() As Byte, _
strPhonebook As String, strEntryName As String, _
Optional blnPasswordRetrieved As Boolean) As Long
Dim rtn As Long
Dim blnPsswrd As Long
Dim bLens As Variant
Dim lngLen As Long, i As Long
bLens = Array(1060&, 1052&, 816&)
'try our three different sizes for RasDialParams
For i = 0 To 2
lngLen = bLens(i)
ReDim bytesOut(lngLen - 1)
CopyMemory bytesOut(0), lngLen, 4
If lngLen = 816& Then
CopyStringToByte bytesOut(4), strEntryName, 20
Else
CopyStringToByte bytesOut(4), strEntryName, 256
End If
rtn = RasGetEntryDialParams(strPhonebook, bytesOut(0), blnPsswrd)
If rtn = 0 Then Exit For
Next i
blnPasswordRetrieved = blnPsswrd
VBRasGetEntryDialParams = rtn
End Function
The following function, VBRasSetEntryDialParams, sets an entry's dial parameters, using an array of bytes. You don't really need this function as you can call on the RasSetEntryDialParams function directly. (see declares at end of this page)
Function VBRasSetEntryDialParams _
(strPhonebook As String, bytesIn() As Byte, _
blnRemovePassword As Boolean) As Long
VBRasSetEntryDialParams = RasSetEntryDialParams _
(strPhonebook, bytesIn(0), blnRemovePassword)
End Function
Apart from just working with an array of bytes, we might also want to work with a class or user defined type that represents the RASDIALPARAMS structure that is VB "friendly" (i.e. variable length strings). Such a structure would probably look like this:
'VB "friendly" RasDialParams Structure
Public Type VBRasDialParams
EntryName As String
PhoneNumber As String
CallbackNumber As String
UserName As String
Password As String
Domain As String
SubEntryIndex As Long
RasDialFunc2CallbackId As Long
End Type
Now, to get populate our VBRasDialParams structure from an array of bytes, we can use this function: BytesToVBRasDialParams
Function BytesToVBRasDialParams(bytesIn() As Byte, _
udtVBRasDialParamsOUT As VBRasDialParams) As Boolean
Dim iPos As Long, lngLen As Long
Dim dwSize As Long
On Error GoTo badBytes
CopyMemory dwSize, bytesIn(0), 4
If dwSize = 816& Then
lngLen = 21&
ElseIf dwSize = 1060& Or dwSize = 1052& Then
lngLen = 257&
Else
'unkown size
Exit Function
End If
iPos = 4
With udtVBRasDialParamsOUT
CopyByteToTrimmedString .EntryName, bytesIn(iPos), lngLen
iPos = iPos + lngLen: lngLen = 129
CopyByteToTrimmedString .PhoneNumber, bytesIn(iPos), lngLen
iPos = iPos + lngLen: lngLen = 129
CopyByteToTrimmedString .CallbackNumber, bytesIn(iPos), lngLen
iPos = iPos + lngLen: lngLen = 257
CopyByteToTrimmedString .UserName, bytesIn(iPos), lngLen
iPos = iPos + lngLen: lngLen = 257
CopyByteToTrimmedString .Password, bytesIn(iPos), lngLen
iPos = iPos + lngLen: lngLen = 16
CopyByteToTrimmedString .Domain, bytesIn(iPos), lngLen
If dwSize > 1052& Then
CopyMemory .SubEntryIndex, bytesIn(1052), 4&
CopyMemory .RasDialFunc2CallbackId, bytesIn(1056), 4&
End If
End With
BytesToVBRasDialParams = True
Exit Function
badBytes:
'error handling goes here ??
BytesToVBRasDialParams = False
End Function
And to get an array of bytes of the appropiate size from our VBRasDialParams structure, we can use this function: VBRasDialParamsToBytes
Function VBRasDialParamsToBytes( _
udtVBRasDialParamsIN As VBRasDialParams, _
bytesOut() As Byte) As Boolean
Dim rtn As Long
Dim blnPsswrd As Long
Dim b() As Byte
Dim bLens As Variant
Dim dwSize As Long, i As Long
Dim iPos As Long, lngLen As Long
bLens = Array(1060&, 1052&, 816&)
For i = 0 To 2
dwSize = bLens(i)
ReDim b(dwSize - 1)
CopyMemory b(0), dwSize, 4
rtn = RasGetEntryDialParams(vbNullString, b(0), blnPsswrd)
If rtn = 623& Then Exit For
Next i
If rtn <> 623& Then Exit Function
On Error GoTo badBytes
ReDim bytesOut(dwSize - 1)
CopyMemory bytesOut(0), dwSize, 4
If dwSize = 816& Then
lngLen = 21&
ElseIf dwSize = 1060& Or dwSize = 1052& Then
lngLen = 257&
Else
'unkown size
Exit Function
End If
iPos = 4
With udtVBRasDialParamsIN
CopyStringToByte bytesOut(iPos), .EntryName, lngLen
iPos = iPos + lngLen: lngLen = 129
CopyStringToByte bytesOut(iPos), .PhoneNumber, lngLen
iPos = iPos + lngLen: lngLen = 129
CopyStringToByte bytesOut(iPos), .CallbackNumber, lngLen
iPos = iPos + lngLen: lngLen = 257
CopyStringToByte bytesOut(iPos), .UserName, lngLen
iPos = iPos + lngLen: lngLen = 257
CopyStringToByte bytesOut(iPos), .Password, lngLen
iPos = iPos + lngLen: lngLen = 16
CopyStringToByte bytesOut(iPos), .Domain, lngLen
If dwSize > 1052& Then
CopyMemory bytesOut(1052), .SubEntryIndex, 4&
CopyMemory bytesOut(1056), .RasDialFunc2CallbackId, 4&
End If
End With
VBRasDialParamsToBytes = True
Exit Function
badBytes:
'error handling goes here ??
VBRasDialParamsToBytes = False
End Function
' helper functions
Sub CopyByteToTrimmedString(strToCopyTo As String, _
bPos As Byte, lngMaxLen As Long)
Dim strTemp As String, lngLen As Long
strTemp = String(lngMaxLen + 1, 0)
CopyMemory ByVal strTemp, bPos, lngMaxLen
lngLen = InStr(strTemp, Chr$(0)) - 1
strToCopyTo = Left$(strTemp, lngLen)
End Sub
Sub CopyStringToByte(bPos As Byte, _
strToCopy As String, lngMaxLen As Long)
Dim lngLen As Long
lngLen = Len(strToCopy)
If lngLen = 0 Then
Exit Sub
ElseIf lngLen > lngMaxLen Then
lngLen = lngMaxLen
End If
CopyMemory bPos, ByVal strToCopy, lngLen
End Sub
Public Declare Function RasGetEntryDialParams _
Lib "rasapi32.dll" Alias "RasGetEntryDialParamsA" _
(ByVal lpszPhonebook As String, _
lpRasDialParams As Any, _
blnPasswordRetrieved As Long) As Long
Public Declare Function RasSetEntryDialParams _
Lib "rasapi32.dll" Alias "RasSetEntryDialParamsA" _
(ByVal lpszPhonebook As String, _
lpRasDialParams As Any, _
ByVal blnRemovePassword As Long) As Long
Public Declare Sub CopyMemory Lib "kernel32" Alias "RtlMoveMemory" _
(Destination As Any, Source As Any, ByVal Length As Long)
See Also: Contents, Introduction, RasDial, RasEnumEntries, RasSetEntryProperties, RasGetEntryProperties.