The VB Watch Extended Functions DLL (vbwFunctionsVB6.dll for VB6) offers powerful features for reporting errors that occur on customer's remote machines. It will bring you all the useful informations needed to find the cause of the error, with only one click from the user.
For that, you need to add it to your global error handler. Default plans coming with VB Watch have it fully implemented and could be used as an example.
How to use
To use the VB Watch Extended Functions DLL in your application, you must create a vbwFunctionsVB6.AdvancedFunctions object and use the properties and functions described below. Example:
Dim vbwAdvancedFunctions As Object
Set vbwAdvancedFunctions = CreateObject("vbwFunctionsVB6.AdvancedFunctions")
vbwAdvancedFunctions.SendMessage "BugReport@MyDomain.com", _
"Error in your application", _
"Running your application, I've encountered this error. See attached file", _
"c:\MyZipFile.zip"
Reference
|
Properties |
Methods and Functions |
|
Property ComponentsUsed As String
This property is used to inform the VB Watch Extended Functions DLL of which components are referenced by the project, so as to include them in the File Version report. You must write exactly:
vbwAdvancedFunctions.ComponentsUsed =
"<VBW COMPONENTS>"
and VB Watch will automatically replace <VBW
COMPONENTS> with the correct value (e.g.
"MSGrid;MSComCtl2"). The list is delimited with semicolons.
If you wish to add other files to the report, use the FileInfo function.
Property DumpFileName As String
Sets the path to the variable report file. This value must be set prior to calling ReportObject.
This value should be the same as the one used for dumping non-object variables (vbwDumpFile), so usually you will write:
vbwAdvancedFunctions.DumpFileName = vbwDumpFile
Property DumpMaxObjectLength As Long
Sets the maximum length in bytes of the report for a single object. This is essentially useful when the ReportObject method misses a circular reference that causes a never ending loop: in such (improbable) case, the loop is broken after the amount of dumped data exceeds the DumpMaxObjectLength value.
Set this value to 0 if you don't wish to limit the length (to use with caution).
Example:
vbwAdvancedFunctions.DumpMaxObjectLength =
1000000 ' reports cannot exceed 1 Mb per object.
Objects that are truncated when being reported are terminated with "{Object Truncated...}".
Property DumpMaxStringLength As Long
Sets the maximum length in bytes of strings objects properties reported by ReportObject.
Set this value to 0 if you don't wish to limit the length (to use with caution).
Example:
vbwAdvancedFunctions.DumpMaxStringLength = 128
Strings that are truncated when being reported are terminated with "{...}".
Property ExcludedProperties As String
This property is used to exclude some sensitive object properties from the report.
The VB Watch Extended Functions DLL is a powerful object that is able to report everything it finds in an object. The problem is that sometimes this data is sensitive: there is internal data that you do not want to expose to the users, and, on the other side, there is data that customers don't want to send you, such as their own databases.
So you should fill the ExcludedProperties with properties that you know they will contain sensitive data (delimited with semicolons). For example, if you are using a tree view for displaying customers data, you may put Nodes for this property. This way the VB Watch Extended Functions DLL will skip dumping the Nodes properties of any object. Example:
vbwAdvancedFunctions.ExcludedProperties = "Nodes;ListSubItems"
Note: for sensitive data that is not in objects but regular variables, fill the Exclude variables from report setting when editing your error handling plan.
In any case it is recommended to raise a fake error and check the generated report before shipping.
Property ExeCommandLine As String
This property is used to inform the VB Watch Extended Functions DLL of the command line value, so as to include it in the File Version report. You should always write:
vbwAdvancedFunctions.ExeCommandLine = Command$
This property is used to inform the VB Watch Extended Functions DLL of the executable, so as to include its file path and version in the File Version report. You should always write:
vbwAdvancedFunctions.ExeInstance = App.hInstance
The ReportObject function of the VB Watch Extended Functions DLL requires this property to be correctly set. It contains the property names of each component used by your project (as well as your vardump encryption key if you provided one). It can only be generated by VB Watch in a specific format so you should always write:
vbwAdvancedFunctions.ObjectInfo = "<VBW OBJECT FILE INFO>"
and VB Watch will automatically replace <VBW OBJECT FILE INFO> with the correct value.
Property VBRuntimeFile As String
This property is used to inform the VB Watch Extended Functions DLL of the VB runtime file, so as to include it in the File Version report. You must write exactly:
vbwAdvancedFunctions.VBRuntimeFile =
"<VBW VBRUNTIME>"
and VB Watch will automatically replace <VBW
VBRUNTIME> with the correct value (e.g. "MSVBVM60.DLL").
Property ShowStatus As Boolean
Set this property to True if you wish to display a Status form to your user while building the report files (see below).
The VB Watch Extended Functions DLL displays its own status form while working to inform the user of what it is currently doing. When you call the ReportObject function, this form is loaded but not hidden when done. The reason is that usually there are a lot of different objects to report. Showing and hiding the status form for each object would cause it to flicker unnecessarily. Thus you are provided with this method that should be called once everything is done. Usage:
vbwAdvancedFunctions.CloseStatusForm
Function FileInfo(FilePath As String) As String
This function retrieves some informations about the file passed as argument. Example:
vbwAdvancedFunctions.FileInfo("C:\WIN98\SYSTEM\MSVBVM60.DLL")
returns:
File=MSVBVM60.DLL
FileVersion=6.0.8495
Date=10/05/99
Size=1 384 448 bytes
Attributes=ReadOnly
LanguageID:040904B0
CompanyName: Microsoft Corporation
FileDescription: Visual Basic Virtual Machine
InternalName: MSVBVM60.DLL
LegalCopyright: Copyright ©
1987-1998 Microsoft Corp.
ProductName: Visual Basic
ProductVersion: 6.00.8495
This function is provided to supplement the GetVersionInfo function which only relies on the components automatically passed via the ComponentsUsed property.
Use it when there are files that you wish to retrieve information from and that are not detected as components by VB Watch.
Function GetSystemInfo() As String
This function returns a string describing the user's system. See sample. Usage:
SystemInfoString = vbwAdvancedFunctions.GetSystemInfo()
Function GetVersionInfo() As String
This function returns a string containing informations about the files referenced by the project. See sample.
Prior to using it, you should set the ComponentsUsed, ExeCommandLine, ExeInstance and VBRuntimeFile properties.
Usage:
VersionInfoString = vbwAdvancedFunctions.GetVersionInfo()
Function ReportObject(ObjectName As String, obj As Object, [lTab As Long]) As Long
This function reports the properties values of the object passed in obj. It uses the name passed in ObjectName and optionally indents the report with a number of tabs of lTab.
The file to which the report is output is defined by DumpFileName.
See a sample containing objects reports.
Example:
success =
vbwAdvancedFunctions.ReportObject("MyControl", MyForm.MyControl(1))
The return value is 0 if successful or one of the following error values:
ERR_DUMP_NO_FILE_ERROR = 1 ' no file specified in DumpFileName
ERR_DUMP_CREATE_FILE_ERROR = 2 ' impossible to create the file specified in DumpFileName
ERR_DUMP_OPEN_FILE_ERROR = 3' impossible to open the file specified in DumpFileName
Function SendMessage(RecipientAddress As String, Subject As String, MessageBody As String, AttachedFile As String) As Long
This function opens the local email messenger (if it is associated to MAPI calls), and prepares a message defined by the RecipientAddress, Subject, MessageBody, AttachedFile parameters.
AttachedFile may contain the path to one file that you wish to attach, or pass an empty string if you do not wish to attach any file.
Note: the message iExamples not sent but ready to go. it is the user's responsability to press the "Send Message Now" button or not.
Example:
success =
vbwAdvancedFunctions.SendMessage("BugReport@MyDomain.com", "Error in your
application", "Running your application, I've encountered
this error. See attached file", "c:\MyZipFile.zip")
The return value is 0 if successful or one of the following error values:
ERR_MAPI_USER_ABORT = 1
ERR_MAPI_E_FAILURE = 2
ERR_MAPI_E_LOGIN_FAILURE = 3
ERR_MAPI_E_DISK_FULL = 4
ERR_MAPI_E_INSUFFICIENT_MEMORY = 5
ERR_MAPI_E_BLK_TOO_SMALL = 6
ERR_MAPI_E_TOO_MANY_SESSIONS = 8
ERR_MAPI_E_TOO_MANY_FILES = 9
ERR_MAPI_E_TOO_MANY_RECIPIENTS = 10
ERR_MAPI_E_ATTACHMENT_NOT_FOUND = 11
ERR_MAPI_E_ATTACHMENT_OPEN_FAILURE = 12
ERR_MAPI_E_ATTACHMENT_WRITE_FAILURE = 13
ERR_MAPI_E_UNKNOWN_RECIPIENT = 14
ERR_MAPI_E_BAD_RECIPTYPE = 15
ERR_MAPI_E_NO_MESSAGES = 16
ERR_MAPI_E_INVALID_MESSAGE = 17
ERR_MAPI_E_TEXT_TOO_LARGE = 18
ERR_MAPI_E_INVALID_SESSION = 19
ERR_MAPI_E_TYPE_NOT_SUPPORTED = 20
ERR_MAPI_E_AMBIGUOUS_RECIPIENT = 21
ERR_MAPI_E_MESSAGE_IN_USE = 22
ERR_MAPI_E_NETWORK_FAILURE = 23
ERR_MAPI_E_INVALID_EDITFIELDS = 24
ERR_MAPI_E_INVALID_RECIPS = 25
ERR_MAPI_E_NOT_SUPPORTED = 26
ERR_MAPI_E_MAPI32_NOT_INSTALLED = 30
ERR_MAPI_UNKNOWN_ERROR = 31
Function ZipDirectory(DirPath As String, ZipFileName As String) As Long
This function zips (that is, compresses to the zip standard) the contents of the directory passed in DirPath into the file specified in ZipFileName.
Example:
success =
vbwAdvancedFunctions.ZipDirectory("c:\MyDirectory\", "c:\MyZipFile.zip")
The return value is 0 if successful or one of the following error values:
ERR_ZIP_EOF = 2 ' unexpected end of zip file
ERR_ZIP_FORM = 3 ' zip file structure error
ERR_ZIP_MEM = 4 ' out of memory
ERR_ZIP_LOGIC = 5 ' internal logic error
ERR_ZIP_BIG = 6 ' entry too large to split
ERR_ZIP_NOTE = 7 ' invalid comment format
ERR_ZIP_TEST = 8 ' zip test (-T) failed or out of memory
ERR_ZIP_ABORT = 9 ' user interrupt or termination
ERR_ZIP_TEMP = 10 ' error using a temp file
ERR_ZIP_READ = 11 ' read or seek error
ERR_ZIP_NONE = 12 ' nothing to do
ERR_ZIP_NAME = 13 ' missing or empty zip file
ERR_ZIP_WRITE = 14 ' error writing to a file
ERR_ZIP_CREAT = 15 ' couldn't open to write
ERR_ZIP_PARMS = 16 ' bad command line
ERR_ZIP_UNKNOWN_ERROR = 31 ' unknown error
Function ZipFiles(ZipFileName As String, FileToZip-1[, FileToZip-2, ... [, FileToZip-n]])) As Long
This function zips (that is, compresses to the zip standard) the list of files passed in FileToZip into the file specified in ZipFileName.
Example:
success =
vbwAdvancedFunctions.ZipFiles("c:\MyZipFile.zip", "c:\SomeDirectory\SomeFile.ext", "c:\OtherDirectory\OtherFile.ext")
The return value is 0 if successful or one of the error values described above for the ZipDirectory function.
Function GetWindowScreenShot(handle As Long) As Picture
This function returns a picture containing the screenshot of the form whose hWnd property as been passed as argument.
Example:
SavePicture vbwAdvancedFunctions.GetWindowScreenShot(Form1.hWnd), "C:\Screenshot.bmp"
Function EncryptString(sString As String, [sKey As String]) As String
This function encrypts a given string with a given key and returns the result.
About the key: If you filled the vardump encryption key in the VB Watch Options, your key will be already embeded in the ObjectInfo property, so you do not need to provide a key unless you wish to overide it.
About security: The encryption uses an ARCFOUR algorythm which is considered secure, but please remember that breaking any encrypted data is just a matter of time. Even if it may take years of computing with today's computers, it may take much less time in the future. Use it at your own risk.
The longer the key is, the more secure it is.
Public Function vbwEncryptString(ByRef sString As String, Optional sKey) As String
On Error Resume Next
If fIsVbwFunctionsInitialized = False Then
' no encryption without vbwFunctions.dll
' you may want to write your own encryption routine
vbwEncryptString = sString
Else
If IsMissing(sKey) Then
' If you filled the vardump encryption key in the VB Watch Options, your key will
' be already embeded in the vbwAdvancedFunctions.ObjectInfo property, so you do not
' have to care about provideing a key
vbwEncryptString = vbwAdvancedFunctions.EncryptString(sString)
Else
' Yet if you wish to overide your default encryption key, simply pass it
' in the sKey parameter
vbwEncryptString = vbwAdvancedFunctions.EncryptString(sString, sKey)
End If
End If
End Function
Function DecryptString(sString As String, [sKey As String]) As String
This functions decrypts strings that were encrypted with the function above. Make sure to reuse the same key !