SPS Blog

Major VFP Encryption Update

Sun, 09 Aug 2009 23:16:26 GMT

The free vfpencryption71.fll and vfpencryption.fll have been updated. Changes include:

Bug fixes for Blowfish encryption (including blocksize and allowing keysize between 8 and 448 bits)
Bug fixes to modes CBC and CFB - operate correctly now.
Added ability to specify padding, key size, block size, and initialization vector (IV) where applicable (these changes allow compatibility with .NET and other encryption systems as well as the ability to adhere specifically to the AES specification as set out in the FIPS 197 Specification).
Added mode OFB to encryption/decryption algorithms.
Padding types supported are Zeroes (NULLs), Spaces (blanks), PKCS7, ANSI X.923, and ISO 10126.
Added HMAC() function that works with all supported hash types.
Added VFP test program files to the downloads that allow developers to see for themselves that return values are correct for various functions provided by the FLL.
Added GenerateKey() function that will return a random key or IV based on some specified rules (parameters).
Corrected and updated documentation (see below).

Please provide feedback here or send me an email if you run into any problems with this latest version. You'll be able to tell from the test program files (Test Vectors) that I did a lot of testing on my own to make sure that this version was solid. I also did a number of tests between .NET System.Security.Cryptography classes (such as RijndaelManaged for instance) and this FLL to ensure that there was a good deal of compatibility.

The vfpencryption71.fll requires the VC++ 7.1 runtimes whereas the vfpencryption.fll requires the VC++ 9.0 runtimes. If you are getting a "FLL is Invalid" error when running either of these FLLs it is because you are missing the runtimes on the system you are deploying your application on. What about the previous vfpencryption.fll that used the VC++ 8.0 runtimes? I continue to update to the latest Visual Studio (10.0 will be next) and I suggest you do the same. Most VFP developers are using the vfpencryption71.fll as the C runtime matches the one used for VFP 9.0 (msvcr71.dll) and it provides the exact same functionality as vfpencryption.fll. However, I have had numerous requests for an updated build of the FLL using the latest Visual Studio, so I include it below.

Download the Latest Version of the vfpencryption71.fll (134 KB approx.)

Download the Latest Version of the vfpencryption.fll (142 KB approx.)

vfpencryption71.fll/vfpencryption.fll Documentation...

Function ENCRYPT()

Signature: Encrypt(cStringtoEncrypt, cSecretKey[, nEncryptionType[, nEncryptionMode[, nPaddingType[, nKeySize[, nBlockSize[, cIV]]]]]])

Parameters:

cStringtoEncrypt - A plain text string that you want to have encrypted, such as "Hello World!"

cSecretKey - A plain text string that is the Key you want used during encryption, such as "My_SeCrEt_KeY".
Please note that keys may need to be of a particular length for certain types of encryption. Refer below for more information.

nEncryptionType - There are currently 5 types of encryption available. The value of this parameter determines that type of encryption used and how long your Secret Key should be. A single character in Visual FoxPro is equal to 1 byte or 8 bits. So an encryption algorithm requiring a 128-bit key would need a Secret Key of 16 characters (16 x 8 = 128).

0 = Rijndael\AES 128 (requires a 16 character Key)
1 = Rijndael\AES 192 (requires a 24 character Key)
2 = Rijndael\AES 256 (requires a 32 character Key) *Default
4 = Blowfish (key between 1 and 56 characters)
8 = TEA (requires a 16 character Key)
1024 = RC4 (Key can be any length)

nEncryptionMode - There are three different modes available for the each of the encryption types listed above. They include: Electronic Code Book (ECB), Cipher Block Chaining (CBC), Cipher Feedback Block (CFB), and Output Feedback Block. The nEncryptionMode parameter does not apply to RC4 encryption (nEncryptionType = 1024).

0 = ECB *Default
1 = CBC
2 = CFB
3 = OFB

nPaddingMode - For Block Ciphers the cStringtoEncrypt is padded to a multiple of the block size for the algorithm. Setting this parameter allows you to specify how this padding is done.

0 = Zeroes (NULLs) *Default
1 = Spaces (blanks)
2 = PKCS7
3 = ANSI X.923
4 = ISO 10126

nKeySize - The size of the cSecretKey in bytes (characters).

nBlockSize - The block size the nEncryptionType should use.

cIV - The Initialization Vector (IV) that should be used for CBC, CFB, and OFB modes should use. This IV should match the specified nBlockSize in total bytes (characters).

Return Value:

Character data type - the encrypted form of cStringtoEncrypt.

Remarks:

When saving the return value of Encrypt() function to a field in a table, remember that Visual FoxPro will append blanks to the end of the string in order to fill the character field to its designated length. This can cause problems when decrypting the data as the spaces will be considered part of the encrypted string. To work around this, I suggest placing a single CHR(0) at the end of the encrypted string when saving it to the table. Then when decrypting the data just the portion prior to the CHR(0) can be sent into the Decrypt() function. This does not apply when using RC4 encryption (nEncryptionType = 1024).

Function DECRYPT()

Signature: Decrypt(cEncryptString, cSecretKey[, nDecryptionType[, nDecryptionMode[, nPaddingType[, nKeySize[, nBlockSize[, cIV]]]]]])

Parameters:

cEncryptedString - A string that has been encrypted using the Encrypt() function.

cSecretKey - A plain text string that is the same Key that you used when you encrypted the data using the Encrypt function, such as "My_SeCrEt_KeY".
Please note that keys may need to be of a particular length for certain types of decryption. Refer below for more information.

nDecryptionType - There are currently 5 types of decryption available and they correspond to the same ones available in Encrypt(). A single character in Visual FoxPro is equal to 1 byte or 8 bits. So an decryption algorithm requiring a 128-bit key would need a Secret Key of 16 characters (16 x 8 = 128).

0 = Rijndael\AES 128 (requires a 16 character Key)
1 = Rijndael\AES 192 (requires a 24 character Key)
2 = Rijndael\AES 256 (requires a 32 character Key) *Default
4 = Blowfish (key between 1 and 56 characters)
8 = TEA (requires a 16 character Key)
1024 = RC4 (Key can be any length)

nDecryptionMode - There are three different modes available for the each of the encryption types listed above. They include: Electronic Code Book (ECB), Cipher Block Chaining (CBC), Cipher Feedback Block (CFB), and Output Feedback Block. The nDecryptionMode parameter does not apply to RC4 decryption (nDecryptionType = 1024).

0 = ECB *Default
1 = CBC
2 = CFB
3 = OFB

nPaddingMode - For Block Ciphers the cStringtoEncrypt is padded to a multiple of the block size for the algorithm. Setting this parameter allows you to specify how this padding is done.

0 = Zeroes (NULLs) *Default
1 = Spaces (blanks)
2 = PKCS7
3 = ANSI X.923
4 = ISO 10126

nKeySize - The size of the cSecretKey in bytes (characters).

nBlockSize - The block size the nEncryptionType should use.

cIV - The Initialization Vector (IV) that should be used for CBC, CFB, and OFB modes should use. This IV should match the specified nBlockSize in total bytes (characters).

Return Value:

Character data type - the decrypted form of cEncryptedString followed by a variable number of CHR(0)s. See Remarks below for further clarification

Remarks:

IMPORTANT: Decryption is done on blocks of memory, so when the decrypt function returns the encrypted string it will be followed by a variable number of CHR(0)s unless the decrypted string just happens to end at exactly the same location as the last block decrypted. These extraneous CHR(0)'s can be removed using a number of Visual FoxPro functions, such as STRTRAN(), CHRTRAN(), or a combination of LEFT() and AT(). This does not apply when using RC4 decryption (nDecryptionType = 1024).

Function ENCRYPTFILE()

Signature: EncryptFile(cFiletoEncrypt, cDestinationFile, cSecretKey[, nEncryptionType[, nEncryptionMode[, nPaddingType[, nKeySize[, nBlockSize[, cIV]]]]]])

Parameters:

cFiletoEncrypt - A plain text string that is the fullpath to the file you wish to be encrypted, such as "C:\SensitiveInfo.doc"

cDestinationFile - A plain text string that is the fullpath to an encrypted file you wish to have created on disk, such as "C:\EncryptedInfo.doc". If this file doesn't exist then it will be created for you.

nEncryptionMode - There are three different modes available for the each of the encryption types listed above. They include: Electronic Code Book (ECB), Cipher Block Chaining (CBC), Cipher Feedback Block (CFB), and Output Feedback Block. This does not apply when using RC4 encryption (nEncryptionType = 1024).

0 = ECB *Default
1 = CBC
2 = CFB
3 = OFB

nPaddingMode - For Block Ciphers the cStringtoEncrypt is padded to a multiple of the block size for the algorithm. Setting this parameter allows you to specify how this padding is done.

0 = Zeroes (NULLs) *Default
1 = Spaces (blanks)
2 = PKCS7
3 = ANSI X.923
4 = ISO 10126

nKeySize - The size of the cSecretKey in bytes (characters).

nBlockSize - The block size the nEncryptionType should use.

cIV - The Initialization Vector (IV) that should be used for CBC, CFB, and OFB modes should use. This IV should match the specified nBlockSize in total bytes (characters).

Return Value:

None

Remarks:

Currently the cFiletoEncrypt and cDestinationFile parameters cannot point to the same file. This may be revised in a future version. But for safety sake, this function requires that the original file be left untouched.

Function DECRYPTFILE()

Signature: DecryptFile(cEncryptedFile, cDestinationFile, cSecretKey[, nDecryptionType[, nDecryptionMode[, nPaddingType[, nKeySize[, nBlockSize[, cIV]]]]]])

Parameters:

cEncyptedFile - A plain text string that is the fullpath to the file you wish to be decrypted, such as "C:\EncryptedInfo.doc"

cDestinationFile - A plain text string that is the fullpath to a decrypted file you wish to have created on disk, such as "C:\SensitiveInfo.doc". If this file doesn't exist then it will be created for you.

nDecryptionMode - There are three different modes available for the each of the encryption types listed above. They include: Electronic Code Book (ECB), Cipher Block Chaining (CBC), Cipher Feedback Block (CFB), and Output Feedback Block. This does not apply when using RC4 decryption (nDecryptionType = 1024).

0 = ECB *Default
1 = CBC
2 = CFB
3 = OFB

nPaddingMode - For Block Ciphers the cStringtoEncrypt is padded to a multiple of the block size for the algorithm. Setting this parameter allows you to specify how this padding is done.

0 = Zeroes (NULLs) *Default
1 = Spaces (blanks)
2 = PKCS7
3 = ANSI X.923
4 = ISO 10126

nKeySize - The size of the cSecretKey in bytes (characters).

nBlockSize - The block size the nEncryptionType should use.

cIV - The Initialization Vector (IV) that should be used for CBC, CFB, and OFB modes should use. This IV should match the specified nBlockSize in total bytes (characters).

Return Value:

None

Remarks:

As with EncryptFile(), the cFiletoEncrypt and cDestinationFile parameters cannot point to the same file.

Function HASH()

Signature: Hash(cStringtoHash[, nHashType])

Parameters:

cStringtoHash - A plain text string you wish to have hashed

nHashType - The type of hash function to generate. There are currently 7 different hash functions supported

1 = SHA1 (a.k.a SHA160)
2 = SHA256
3 = SHA384
4 = SHA512 *Default
5 = MD5
6 = RIPEMD128
7 = RIPEMD160

Return Value:

Binary Character Data - the hash for cStringtoHash.

Remarks:

The hash is returned as a series of binary characters. However, it is more common to see hashes in a hexBinary format. This can be accomplished in Visual FoxPro by taking the return of the Hash() function and sending it in as a parameter to the STRCONV() function. For example:

?STRCONV(Hash("Some String"), 15) && hexBinary Hash

Function HASHFILE()

Signature: HashFile(cFileName[, nHashType])

Parameters:

cFileName - The fullpath and name of an existing file you wish to generate a message digest for

nHashType - The type of hash function to generate. There are currently 7 different hash functions supported

1 = SHA1 (a.k.a SHA160)
2 = SHA256
3 = SHA384
4 = SHA512 *Default
5 = MD5
6 = RIPEMD128
7 = RIPEMD160

Return Value:

Binary Character Data - the hash for cFileName.

Remarks:

The hash is returned as a series of binary characters. However, it is more common to see hashes in a hexBinary format. This can be accomplished in Visual FoxPro by taking the return of the HashFile() function and sending it in as a parameter to the STRCONV() function. For example:

?STRCONV(HashFile("C:\MyFile.txt"), 15) && hexBinary Hash

Function HASHRECORD()

Signature: HashRecord(cAlias[, nHashType[,lIncludeMemos]])

Parameters:

cAlias - The table alias containing the record to be hashed

nHashType - The type of hash function to generate. There are currently 7 different hash functions supported

1 = SHA1 (a.k.a SHA160)
2 = SHA256
3 = SHA384
4 = SHA512 *Default
5 = MD5
6 = RIPEMD128
7 = RIPEMD160

lIncludeMemos - Flag determining whether Memo fields should be included when generating the message digest. .T. = Include Memo Fields, .F. = Exclude Memo Fields

Return Value:

Binary Character Data - the hash for the current record in cAlias.

Remarks:

The hash is returned as a series of binary characters. However, it is more common to see hashes in a hexBinary format. This can be accomplished in Visual FoxPro by taking the return of the HashRecord() function and sending it in as a parameter to the STRCONV() function. For example:

?STRCONV(HashRecord("MyTable",5,.T.), 15) && hexBinary Hash

Function HMAC()

Signature: HMAC(cStringtoHash, cSecretKey[, nHashType])

Parameters:

cStringtoHash - A plain text string you wish to have a keyed Hash Message Authentication Code (HMAC) generated from.

cSecretKey - A plain text string that is the Key you want used during generation of the keyed HMAC.

nHashType - The type of hash function to use when generating the keyed HMAC. There are currently 7 different hash functions supported:

1 = SHA1 (a.k.a SHA160)
2 = SHA256
3 = SHA384
4 = SHA512 *Default
5 = MD5
6 = RIPEMD128
7 = RIPEMD160

Return Value:

Binary Character Data - the HMAC for the given cStringtoHash and cSecretKey.

Remarks:

The HMAC is returned as a series of binary characters. However, it is more common to see HMACs in a hexBinary format. This can be accomplished in Visual FoxPro by taking the return of the HMAC() function and sending it in as a parameter to STRCONV(cReturn, 15).

Function CRC()

Signature: CRC(cExpression[, nCRCType])

Parameters:

cExpression - The string you wish to have a CRC generated for

nCRCType - The type of CRC to generate. There are currently 2 different CRC types supported

1 = 16-bit
2 = 32-bit

Return Value:

Numeric Data - the CRC for cExpression.

Remarks:

Function CRCFILE()

Signature: CRCFile(cFileName[, nCRCType])

Parameters:

cFileName - The fullpath and name of an existing file you wish to generate a CRC for

nCRCType - The type of CRC to generate. There are currently 2 different CRC types supported

1 = 16-bit
2 = 32-bit

Return Value:

Numeric Data - the CRC for cFileName.

Remarks:

The CRC that is returned is unsigned, which means that the returned 16-bit CRC needs to be treated as a 4 Byte numeric value and the 32-bit CRC as a 8 byte numeric value in Visual FoxPro.

Function CRCRECORD()

Signature: CRCRecord(cAlias[, nCRCType[,lIncludeMemos]])

Parameters:

cAlias - The table alias containing the record to be hashed

nCRCType - The type of CRC to generate. There are currently 2 different CRC types supported

1 = 16-bit
2 = 32-bit

lIncludeMemos - Flag determining whether Memo fields should be included when generating the message digest. .T. = Include Memo Fields, .F. = Exclude Memo Fields

Return Value:

Numeric Data - the CRC for the current record in cAlias .

Remarks:

The CRC that is returned is unsigned, which means that the returned 16-bit CRC needs to be treated as a 4 Byte numeric value and the 32-bit CRC as a 8 byte numeric value in Visual FoxPro. The operation of the CRC() function presented here is quite similar to Visual FoxPro's Sys(2017) function, however you will find that this CRC function is faster than Visual FoxPro's Sys(2017). Also, this function allows you to specify a table alias, which allows CRCs to be created for a record in a table other than the currently selected work area. On the downside, this function does not allow you to specify a comma delimited list of fields to exclude like Sys(2017) does.

Function GENERATEKEY()

Signature: GenerateKey(nKeySize[, lIncludeNumbers[, lIncludeUpper[, lIncludeSpecial]]])

Parameters:

nKeySize - The size of the key to be returned in bytes (total characters you want returned)

lIncludeNumbers - Flag determining whether Numbers (digits "0-9") should be included when generating the key. .T. = Include Numbers, .F. = Exclude Numbers (default)

lIncludeUpper - Flag determining whether uppercase characters should be included when generating the key. .T. = Include Uppercase Characters, .F. = Exclude Uppercase Characters (default)

lIncludeSpecial - Flag determining whether Special Characters (characters "{}|\\]?[\":;'><,./~!@#$%^&*()_+`-=") should be included when generating the key. .T. = Include Special Characters, .F. = Exclude Special Characters (default)

Return Value:

Character Data - the random key generated based on the specified rules.

Remarks:

The key generated is a random set of lowercase characters by default. To add additional possible characters for generating the key you can use the parameters (2-4) as specified. The random keys returned can be used for the other FLL functions that allow for a cSecretKey or cIV. This function is provided as a convenience function for developers needing to produce a random key quickly and easily.

This weblog is sponsored by SweetPotato Software, Inc.

Apply Application Manifest at Compile Time with Projecthook

Mon, 03 Aug 2009 11:50:30 GMT

Some Time Ago...

I wrote a blog entry, PE Files, UAC, Reg-Free COM, and Other Crazy Stuff - Part 2, that detailed how to view and edit the application manifest that is inserted into VFP compiled modules. I also took some time to explain why someone would want to do such a thing. The top two reasons most VFP developers want to do this is to elevate permissions under Window's User Account Control (UAC) and to provide for Registration-Free COM. I guess you may also find the need to edit or add strings to the PE file's String Table resource (minority of VFP developers) which is provided for as well.

While the code and concepts detailed in that previous blog entry were advanced and pretty decent (if i do say so myself), it suffered from a couple of bugs and most VFP developers probably found it more than a little difficult to implement "out-of-the-box" for their projects that needed elevated UAC permissions or Reg-Free COM. I attempt to make things slightly more straight-forward and bug-free in this blog entry.

Enter the ProjectHook Class

There's plenty of good information on the ProjectHook class online and in the VFP 9.0 SP2 help file (get the latest and greatest help file out on VFPX), so I won't go into a great amount of detail here. I simply wanted an easy way to apply a new manifest to a VFP executable after I had built a project. The ProjectHook class provides a BeforeBuild event where I can get the fullpath of the EXE being built and an AfterBuild event which allows me to perform operations immediately after the EXE is built. So, this class provided exactly what i needed and made applying a modified manifest a breeze.

How to Use ProjectHookEx.vcx

In order to use the projecthookex.vcx (download provided at the bottom of this blog entry), you simply need to unzip and copy it somewhere and then open up one of your projects and go into the Project Information dialog (accessible either by right-clicking the project or under the Project system menu... look for Project Info) and set the Project Class property as shown in the following screen shot...

...then simply click OK, exit your project and reopen your project. The projecthook isn't instantiated until you reopen the project for the first time after setting the Project Class property.

The default settings for the hookex class are set so that the default VFP 9.0 SP2 manifest, which has its trustinfo set to asInvoker, is changed to requireAdministrator. Take a look inside hookex's AfterBuild event for the code that accomplishes this (short and sweet). You'll see a couple commented out lines of code in the AfterBuild event that show how to accomplish Reg-Free COM and String Table resource edits as well. In any event, once the Project Class is set for your project hookex will be instantiated and ready to go any time you open and build your project. When the manifest is applied it will be echoed to the screen so you can see it and ensure that it has been applied (you can turn this off by changing the moduleresourceeditor class's showmanifestafterapplying property if you so desire).

External Manifests Anyone?

For those of you that prefer to use an external manifest for your executables, you can do so by setting the moduleresourceeditor class's externalmanifest property. The cool thing about this is that the myproj.exe.manifest file is created in the same directory as your executable and the executable's internal manifest is removed to prevent it from interfering with your external manifest. Then you can edit the external manifest using favorite XML editor or even notepad. This was one of the enhancements I added to this that is not in the code that I posted in the original blog entry regarding PE Assembly/Application Manifests.

What's Next

There are plenty of improvements and enhancements (automatically searching project for all COM components and automatically adding them to the manifest for instance) that could be made to this class and I hope that my readers will make suggestions and even try their hand at coding a few. There are lots of good uses for VFP's ProjectHook class. I'd love to hear from you and what you feel needs to be done to improve this ProjectHook class. But, I'm cool if you just want to read this, download the class library and use it. Until next time... VFP Rocks!

Download the Latest Version of the ProjectHookEx Class Library (12 KB approx.)

This weblog is sponsored by SweetPotato Software, Inc.

Visual Foxpro JSON Class Update

Craig Boyd — Fri, 19 Dec 2008 09:43:59 GMT

JSON Class Update
Since my initial post regarding this class, work has continued improving it. A number of fixes and enhancement can be found in the latest version...

Fixes to parse method - There was a problem with brace matching for "{}" and "[]" when nested in certain ways.
Fixes to UseUTCDatetime functionality - rules are now as follows:

UseUTCDateTime = .F. && Datetimes will stringify including Local offset from UTC
UseUTCDateTime = .T. && Datetimes will stringify as UTC equivalent for Local
Parse() && will always return Local equivalent

Fixes to GetTimezoneOffset method - now respects Standard/Daylight boundaries of datetimes
Fixed Stringify - cursors are serialized to valid JSON now
Added KeyForCursor property - this allows a JSON key to be specified for identifying cursors (defaulted to "VFPData")
Enhanced Stringify and Parse methods - they now handle the VFP Collection class with aplomb
Added KeyForItems property - when serializing Collections, the key for the contained JSON object's array property can be defined (defaulted to "items")
Renamed DateSerializationType property - it is now ParseDateType
Enhanced Parse - JSON class will now (optionally) respect Class and ClassLibrary properties if they exist in a JSON object being deserialized (see ParseRespectClass property). This means that if you Stringify() a VFP Form and then Parse() the JSON (with ParseRespectClass = .T.) you will get a Form object back rather than an Empty object with the same properties as the Form.

I would consider the JSON class production-ready at this point. This doesn't mean that bugs won't be found in the future, but it has been hammered on enough that I wouldn't hesitate to use it in a production application.

Visual FoxPro Now Listed
I got in touch with Douglas Crockford and was able to get Visual FoxPro listed on JSON.org with a link to my initial post. I appreciate Douglas Crockford taking the time out of his busy schedule to list Visual FoxPro on the JSON site.

Special Thank You
Nearly all of the fixes and enhancements provided in this version of the JSON class were made possible by the help and prodding I received from Frank Dietrich of Berlin. He is an extremely bright fellow. Implementing the Timezone and Daylight vs. Standard stuff drove us both to the brink. I sincerely doubt I could have done it without his help.

Download the JSON class library (approx. 59 KB)

The download contains the JSON class in both VCX and PRG format. They are the same. Use whichever one you prefer.

This weblog is sponsored by SweetPotato Software, Inc.

VFPCompression Update - A Couple of Fixes and a Slight Enhancement

Craig Boyd — Mon, 08 Dec 2008 11:35:21 GMT

VFPCompression Bug Fixes
I received some really good feedback after posting my previous blog entry concerning this library from Curt Hamlin and Eduard. There were two bugs there that I felt needed some immediate attention, so in this blog entry I present a version of VFPCompression that addresses them.

The first bug was the one that Curt Hamlin ran into where something screwy was going on if the zip file wasn't somehow relative to the files or folders being zipped. The following code...

ZipOpen("F:\MyZipFile.zip") && note zip is going to F: drive
ZipFolder("C:\MyFolder\", .F.) && note folder being zipped is on C: drive
ZipClose()

...would result in an empty zip file being created (not good). While the other bug was the one that Eduard reported where the ZipFolderQuick function wasn't applying the optional password to the files being zipped. To make a long story short, I was able to verify that these were actual bugs in the library, and I have uploaded a new version of VFPCompression.fll that fixes them.

VFPCompression Enhancement
Something that I didn't like in the FLL was that in order to extract the contents of a zip to a particular folder that folder had to already exist in the file system. I decided that the FLL should try and create a folder if it doesn't already exist when extracting, which it now does.

VFPCompression FLL Download (approx. 38 KB)

The VFP Compression Library sample code and documentation can still be found at my previous blog entry.

This weblog is sponsored by SweetPotato Software, Inc.

Visual FoxPro and Windows Desktop Search

Craig Boyd — Mon, 08 Dec 2008 10:08:19 GMT

Search Revisited
I've spoken about the work I was doing with Windows Desktop Search (WDS) and Visual FoxPro before on this blog here and here. Though the project I present in this blog entry began when WDS 2.0 was the latest and greatest, it was rewritten for WDS 3.0 and has been revamped some and tested with WDS 4.0 (the latest and greatest as of this writing). In any event, this project was being considered by Microsoft (MS) for inclusion as part of Sedna, but never made the cut. I later obtained permission from MS to release it on my own, but haven't found time to test it or post it until now.

Foxy Search Value
There are many things of value in the Foxy Search sample...

Shows how to properly use the WDS OLEDB Provider from VFP.
Provides a guide to the proper SQL syntax for WDS.
Includes a list of fields available via the OLEDB Provider. (see fields.dbf)
Provides VFP develpers a class for working with WDS and ultimately returning search results as VFP cursors.

If nothing else, Foxy Search provides a pretty good sample for messing with when trying out various aspects of WDS. It does not provide examples of the creation or use of IFilters, handlers, or thumbnail extractors - if you are looking for those you'll have to look elsewhere at the moment.

Foxy Search Errors
It should be noted that Foxy Search can, and will, throw errors depending on the combinations of display fields, filters, and/or sorting chosen. Rather than attempt to restrict what can and can't be chosen to lessen the errors, I felt it was easier to just allow the developer using it to mess around with everything and see what is and what isn't possible. Feel free to change the Throw Error in the Catch of the form's GetSearchResults method to handle the various errors you run into if you feel like it (or just comment it out if you want it to fail silently).

Don't Have Windows Desktop Search?
You can check whether you have Windows Desktop Search and what version of it is on your system by looking in the Control Panel's Add & Remove Programs or by looking in your registry under the "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Desktop Search" key where there is a "Version" value. If you don't have WDS (or you are running an outdated version) you can go to the MS site to download and install WDS v4.0.

Until next time... Visual FoxPro Rocks!

Download Foxy Search 1.0 (approx. 89 KB)

Figure 1: Shows Foxy Search being used to find all of the FOXUSER files on my system and display information about each result.

This weblog is sponsored by SweetPotato Software, Inc.

VFPConnection Update - HTTP Post, FTP Commands and More...

Craig Boyd — Fri, 05 Dec 2008 15:54:45 GMT

VFPConnection Library Update
It hasn't been too many days since I posted an update to this library. The two big enhancements in that update was SSL support and a mechanism for tracing. It was fairly well received and appeared to work well for those that downloaded it, but I mentioned at the end of that blog entry that I wanted to do a few other enhancements surrounding FTP commands and HTTP Posts. This update provides that functionality among other things.

What's New
I've added 10 new functions to the FLL and documentation. These include:

HTTPSimplePost
HTTPPost
FTPCommands
FTPSCommands
URLEncode
URLDecode
DateStrToEpochSec
SetConnectTimeout
SetResponseTimeout
CurlVersion

I've also done some refactoring within the library and a few performance enhancements (though it was pretty darn fast to already).

What's Next
If you download and use this library then you might consider taking the time to provide me feedback and any suggestions you may have for further improving it. The update provided here is a testament to the fact that your feedback is valuable and an integral part of the improvement process for the stuff I provide to the VFP Community.

Until next time... Visual FoxPro Rocks!

VFPConnection FLL Download (400 KB approx.)

VFPConnection.FLL Sample Use Code:

*!* The code below is not designed to run all at once
*!* Run the individual examples seperately

********************************************************************
*!* Upload Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEGet("File:///C:\Source.txt", "C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* FTP
?FTPGet("FTP://UserName:Password@somedomain.com/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* FTPS
?FTPSGet("FTPS://UserName:Password@somedomain.com:21/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* HTTP
?HTTPGet("http://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")
*!* HTTPS
?HTTPSGet("https://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* Download Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEPut("C:\Source.txt", "File:///C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* FTP
?FTPPut("C:\Source.zip", "FTP://UserName:Password@somedomain.com/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* FTPS
?FTPSPut("C:\Source.zip", "FTPS://UserName:Password@somedomain.com:21/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* HTTP
?HTTPPut("C:\Source.htm", "http://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")
*!* HTTPS
?HTTPSPut("C:\Source.htm", "https://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* To String Examples
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
*!* FILE
?FILEToStr("C:\Source.txt")
*!* FTP
?FTPTOSTR("FTP://UserName:Password@somedomain.com:21/directory/Source.txt")
*!* FTPS
?FTPSTOSTR("FTPS://UserName:Password@somedomain.com:21/directory/Source.txt")
*!* HTTP
?HTTPToStr("http://www.somedomain.com/Source.txt")
*!* HTTPS
?HTTPSToStr("https://www.somedomain.com/Source.txt")
SET LIBRARY TO

********************************************************************
*!* HTTP Post Examples
********************************************************************
*!* Simple HTTP Post
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL lcPost
m.lcPost = "fname=John&lname=Smith"
?HttpSimplePost("http://www.snee.com/xml/crud/posttest.cgi", m.lcPost, "", "MyTrace()")
SET LIBRARY TO

*!* MultiPart/Form-Data HTTP Post
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL ARRAY aryPost(2,2)
aryPost(1,1) = "fname" && name
aryPost(1,2) = "test first" && value
aryPost(2,1) = "lname" && name
aryPost(2,2) = "test last" && value
?HttpPost("http://www.cs.tut.fi/cgi-bin/run/~jkorpela/echo.cgi", @aryPost, "", "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* FTP Commands Example
********************************************************************
*!* Rename FTP Directory
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL ARRAY aryFTPCommands(4)
aryFTPCommands(1) = "CWD /"
aryFTPCommands(2) = "PWD"
aryFTPCommands(3) = "RNFR MyDir"
aryFTPCommands(4) = "RNTO RenamedMyDir"
?FTPCommands("FTP://username:password@somedomain.com/", @aryFTPCommands, "MyTrace()")
*!* ?FTPSCommands("FTPS://username:password@somedomain.com/", @aryFTPCommands, "MyTrace()")
SET LIBRARY TO

********************************************************************
*!* URL Encode/Decode Example
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
LOCAL lcString, lcEncoded, lcDecoded
m.lcString = "A!B@C#D$E%F^G&H*I(J)K_L-M=N+O[P]Q{R}S|T\U:V;W'X,Y.Z<0> 1/2?3©4©5©6©7©8©9"
m.lcEncoded = UrlEncode(m.lcString)
m.lcDecoded = UrlDecode(m.lcEncoded)
?"Escaped: " + m.lcEncoded
?"Unescaped: " + m.lcDecoded
?"Original : " + m.lcString
SET LIBRARY TO

********************************************************************
*!* Setting Timeouts Example
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
SetConnectTimeout(30) && Default is 10 seconds
SetResponseTimeout(30) && Default is 10 seconds
SET LIBRARY TO

********************************************************************
*!* Datetime String to the number of seconds from Epoch (12 Midnight on January 1, 1970)
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
?DateStrToEpochSec("Sun, 06 Nov 1994 08:49:37 GMT")
?DateStrToEpochSec("Sunday, 06-Nov-94 08:49:37 GMT")
?DateStrToEpochSec("Sun Nov 6 08:49:37 1994")
?DateStrToEpochSec("06 Nov 1994 08:49:37 GMT")
?DateStrToEpochSec("06-Nov-94 08:49:37 GMT")
?DateStrToEpochSec("Nov 6 08:49:37 1994")
?DateStrToEpochSec("06 Nov 1994 08:49:37")
?DateStrToEpochSec("06-Nov-94 08:49:37")
?DateStrToEpochSec("1994 Nov 6 08:49:37")
?DateStrToEpochSec("GMT 08:49:37 06-Nov-94 Sunday")
?DateStrToEpochSec("94 6 Nov 08:49:37")
?DateStrToEpochSec("1994 Nov 6")
?DateStrToEpochSec("06-Nov-94")
?DateStrToEpochSec("Sun Nov 6 94")
?DateStrToEpochSec("1994.Nov.6")
?DateStrToEpochSec("Sun/Nov/6/94/GMT")
?DateStrToEpochSec("Sun, 06 Nov 1994 08:49:37 CET")
?DateStrToEpochSec("06 Nov 1994 08:49:37 EST")
?DateStrToEpochSec("Sun, 12 Sep 2004 15:05:58 -0700")
?DateStrToEpochSec("Sat, 11 Sep 2004 21:32:11 +0200")
?DateStrToEpochSec("20040912 15:05:58 -0700")
?DateStrToEpochSec("20040911 +0200")
SET LIBRARY TO

********************************************************************
*!* Determine the version of libcurl and OpenSSL that were used for VFPConnection.fll
********************************************************************
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))
?CURLVERSION()
SET LIBRARY TO

***********************
FUNCTION MyProgress() && Callback from the FLL - can be used to track operation progress
***********************
*!* You can create your own function, procedure or method to handle this and name it whatever you want.
*!* The nConnectTotalBytes and nConnectBytesSoFar are private variables created on-the-fly by the FLL
?m.nConnectTotalBytes
?m.nConnectBytesSoFar
ENDFUNC

***********************
FUNCTION MyTrace() && Callback from the FLL - used to provide a detailed trace of the operation
***********************
*!* You can create your own function, procedure or method to handle this and name it whatever you want.
*!* The nTraceDataType and cTraceData are private variables created on-the-fly by the FLL
#DEFINE TYPE_TEXT 0
#DEFINE TYPE_HEADER_IN 1
#DEFINE TYPE_HEADER_OUT 2
#DEFINE TYPE_DATA_IN 3
#DEFINE TYPE_DATA_OUT 4
#DEFINE TYPE_SSL_DATA_IN 5
#DEFINE TYPE_SSL_DATA_OUT 6
#DEFINE TYPE_END 7
?ICASE(m.nTraceDataType = TYPE_TEXT, "STATUS:", ;
m.nTraceDataType = TYPE_HEADER_IN, " , ;
m.nTraceDataType = TYPE_HEADER_OUT, ">SEND HEADER: ", ;
m.nTraceDataType = TYPE_DATA_IN, " , ;
m.nTraceDataType = TYPE_DATA_OUT, ">SEND DATA: ", ;
m.nTraceDataType = TYPE_SSL_DATA_IN, " , ;
m.nTraceDataType = TYPE_SSL_DATA_OUT, ">SEND SSL DATA: ", ;
m.nTraceDataType = TYPE_END, "END: ", "UNKNOWN: ")
??m.cTraceData
ENDFUNC

VFPConnection.FLL Documenation:

Function FTPGet()

Signature: FTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

Function FTPSGet()

Signature: FTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

Function HTTPGet()

Signature: HTTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a website.

Function HTTPSGet()

Signature: HTTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

Function FILEGet()

Signature: FILEGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The full path and file name to the file you wish to copy.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback – An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file from a local or remote location.

The format for the cSourceURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cSourceURL as “FILE:// C:\MyDir\MyFile.zip”.

Function FTPPut()

Signature: FTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

Function FTPSPut()

Signature: FTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

Function HTTPPut()

Signature: HTTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website.

Function HTTPSPut()

Signature: HTTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

Function FILEPut()

Signature: FILEPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want copied.

cDestinationURL - The full path and file name where the file specified in cSource should be copied to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file to a local or remote location.

The format for the cDestinationURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cDestinationURL as “FILE:// C:\MyDir\MyFile.zip”.

Function FTPToStr()

Signature: FTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file from an FTP site as a string.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

Function FTPSToStr()

Signature: FTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file as a string from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

Function HTTPToStr()

Signature: HTTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file from a website as a string.

Function HTTPSToStr()

Signature: HTTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file as a string from a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

Function HTTPSimplePost()

Signature: HTTPSimplePost(cPostURL, cPostData[, cProgressCallback[, cTraceCallback]])

Parameters:

cPostURL - The URL to which you want to post.

cPostData - A string consisting of a series of key-value pairs.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The key-value pairs sent to cPostData are in the form of key1=value1. Additional key-value pairs must be delimited by "&", such as "firstname=John&lastname=Smith".

Function HTTPPost()

Signature: HTTPPost(cPostURL, aPostData[, cProgressCallback[, cTraceCallback]])

Parameters:

cPostURL - The URL to the file you wish to download.

aPostData - A multi-dimensional array containing key-value pairs

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The aPostData array must be sent in by reference. The key-value pairs in aPostData must have the keys in column 1 and the values in column 2, such as:

aPostData(1,1) = "firstname"
aPostData(1,2) = "John"
aPostData(2,1) = "lastname"
aPostData(2,2) = "Smith"

Function FTPCommands()

Signature: FTPCommands(cFTPURL, aCommands[, cProgressCallback[, cTraceCallback]])

Parameters:

cFTPURL - The URL to the FTP site you wish to interact with.

aCommands - A single dimension array containing the commands you wish to have run on the FTP site.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

In order to specify port or login information you would simply include them in cFTPURL, such as “FTP://myusername:mypassword@myftpsite.com:21/.

The aCommands array must be sent in by reference. The aCommands is an array of FTP commands (as defined by RFC 959), such as:

aCommands(1) = "CWD /"
aCommands(2) = "PWD"
aCommands(3) = "RNFR MyDir"
aCommands(4) = "RNTO RenamedMyDir"

Function FTPSCommands()

Signature: FTPSCommands(cFTPSURL, aCommands[, cProgressCallback[, cTraceCallback]])

Parameters:

cFTPSURL - The URL to the FTP site you wish to interact with.

aCommands - A single dimension array containing the commands you wish to have run on the FTP site.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

In order to specify port or login information you would simply include them in cFTPSURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/.

The aCommands array must be sent in by reference. The aCommands is an array of FTP commands (as defined by RFC 959), such as:

aCommands(1) = "CWD /"
aCommands(2) = "PWD"
aCommands(3) = "RNFR MyDir"
aCommands(4) = "RNTO RenamedMyDir"

Function URLEncode()

Signature: URLEncode(cString)

Parameters:

cString - The string you want encoded (escaped).

Return Value:

Character - returns the encoded equivalent of cString.

Remarks:

This function provides libcurl's "URL Escape" functionality. Any character in cString that is not a-z, A-Z, or 0-9 will be deemed unsafe and be replaced with a "%" followed by the unsafe character's hex equivalent. For instance spaces are replaced with %20 because the ASCII value of a space is 32 (0x20 in hex).

Function URLDecode()

Signature: URLDecode(cString)

Parameters:

cString - The string you want decoded (unescaped).

Return Value:

Character - returns the decoded equivalent of cString.

Remarks:

This function provides libcurl's "URL Unescape" functionality. Any character in cString that has been escaped/encoded with a "%" followed by its hex equivalent will be decoded to its plaintext equivalent. For instance %20 will be turned back into a space - CHR(32).

Function SetConnectTimeout()

Signature: SetConnectTimeout(nSeconds)

Parameters:

nSeconds - The number of seconds any connection operation in VFPConnection should wait before failing due to timeout.

Return Value:

None

Remarks:

This function effects all connection operations in VFPConnection. The default value for the connection timeout is 10 seconds.

Function SetResponseTimeout()

Signature: SetResponseTimeout(nSeconds)

Parameters:

nSeconds - The number of seconds any operation in VFPConnection should wait for a response before failing due to timeout.

Return Value:

None

Remarks:

This function effects all operations in VFPConnection that are designed to wait for a server response. The default value for the response timeout is 10 seconds.

Function DateStrToEpochSec()

Signature: DateStrToEpochSec(cDateTime)

Parameters:

cDateTime - A datetime string in one of the many formats.

Return Value:

Numeric - returns the number of seconds between Epoch and the datetime specified by cDateTime.

Remarks:

This function is useful when attempting to convert datetime strings you may encounter when working with web-based applications. RFC2616 specifies which datetime string formats are acceptable for HTTP applications and, in short, there are a lot of them. For instance...

Sun, 06 Nov 1994 08:49:37 GMT
Sunday, 06-Nov-94 08:49:37 GMT
Sun Nov 6 08:49:37 1994
06 Nov 1994 08:49:37 GMT
06-Nov-94 08:49:37 GMT
Nov 6 08:49:37 1994
06 Nov 1994 08:49:37
06-Nov-94 08:49:37
1994 Nov 6 08:49:37
GMT 08:49:37 06-Nov-94 Sunday
94 6 Nov 08:49:37
1994 Nov 606-Nov-94
Sun Nov 6 94
1994.Nov.6
Sun/Nov/6/94/GMT
Sun, 06 Nov 1994 08:49:37 CET
06 Nov 1994 08:49:37 EST
Sun, 12 Sep 2004 15:05:58 -0700
Sat, 11 Sep 2004 21:32:11 +0200
20040912 15:05:58 -0700
20040911 +0200

...are all acceptable. There are also a number of situations where you may be required to use or know the number of seconds since midnight January 1, 1970 (a.k.a. epoch - due to unix and POSIX systems which count time this way). In any event, this function is provided as a crutch if needed.

Function CurlVersion()

Signature: CurlVersion()

Parameters:

None

Return Value:

String - the versions of libcurl and OpenSSL that were used in VFPConnection

Remarks:

This may be of some interest to VFP developers who are asking for enhancements or want to ensure that this library is using the latest and greatest. The static libraries for libcurl and OpenSSL were both built from the latest source available at the time using Visual Studio 2003 and ActivePerl.

This weblog is sponsored by SweetPotato Software, Inc.

VFPCompression Update - Fix and ZipFile Comment Support

Craig Boyd — Mon, 01 Dec 2008 02:12:25 GMT

VFPCompression Update
This update contains a fix that effects the Unzip routines and a new function called ZipComment(). I've also updated the sample code and documentation that is provided with this library.

The bug that was fixed pertained to 0 byte (length) files were being ignored when a zip file's contents were extracted. The Zip routines were handling the 0 byte length files correctly.

The ZipComment() function allows you to add, replace or delete the global zipfile comment for a specified zip file. The code at the bottom of this blog entry shows an example of its use and the documentation now includes this function.

Special Thank You
Special thanks goes out to Mike Sue-Ping who posted out on the Universal Thread about the bug that is fixed in this update.

What's Next
I still plan to add more functionality to this FLL (ability to create cabs and self-extracting archives, better error handling, etc.). I'm hopeful that those of you that download this library will take the time to provide me feedback and any suggestions you may have for further improving it. If you do find a bug, please comment on it here and/or contact me directly. Note the "Contact Craig Boyd" link to the right of this blog entry.

Until next time... Visual FoxPro Rocks!

VFP Compression Update:

VFPCompression FLL Download (37 KB approx.)

VFP Compression Sample Code:

****************************
*!* Example 1
****************************
*!* Zip a file quickly with or without password protection.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFileQuick("C:\MyFile1.txt")
?ZipFileQuick("C:\MyFile2.txt", "MyPassword")
SET LIBRARY TO

****************************
*!* Example 2
****************************
*!* Zip a folder quickly with or without respect
*!* for relative pathing of the files. Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipFolderQuick("C:\MyFolder")
?ZipFolderQuick("C:\MyFolder2", .T., "MyPassword")
?ZipFolderQuick("C:\MyFolder2", .F., "MyPassword")
SET LIBRARY TO

****************************
*!* Example 3
****************************
*!* Unzip a zip file quickly with or without respect
*!* for relative pathing of the files. Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?UnzipQuick("C:\MyFile.zip", "C:\")
?UnzipQuick("C:\MyFolder.zip", "C:\", .T.)
?UnzipQuick("C:\MyFolder.zip", "C:\", .F., "MyPassword")
SET LIBRARY TO

****************************
*!* Example 4
****************************
*!* Create a zip file, add some files to it
*!* and then close it when done. Respect
*!* for relative pathing and Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFile("C:\SomeFile.txt", .F.)
?ZipFile("C:\AnotherFile.txt", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO

****************************
*!* Example 5
****************************
*!* Create a zip file, add some folders to it
*!* and then close it when done. Respect
*!* for relative pathing and Password
*!* protection can be included if desired.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
?ZipOpen("C:\MyZipFile.zip")
*!* ?ZipOpen("MyZipFile.zip", "C:\", .F.)
?ZipFolder("C:\MyFolder\", .F.) && trailing backslash is optional
?ZipFolder("C:\AnotherFolder", .F., "MyPassword")
?ZipClose()
SET LIBRARY TO

****************************
*!* Example 6
****************************
*!* Compress and decompress a string in memory.
*!* The amount of compression is pretty remarkable.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
CLEAR
lcOriginal = REPLICATE("Visual FoxPro Rocks!",100)
?"Original Length: " + TRANSFORM(LEN(lcOriginal))
?
lcCompressed = ZipString(lcOriginal)
?"Compressed: " + lcCompressed
?"Compressed Length: " + TRANSFORM(LEN(lcCompressed))
?
?"Length Savings: " + TRANSFORM(LEN(lcOriginal) - LEN(lcCompressed)) + " bytes"
?
lcUncompressed = UnzipString(lcCompressed)
*!* ?"Uncompressed: " + lcUncompressed
?"Uncompressed Length: " + TRANSFORM(LEN(lcUncompressed))
?"Equals Original: " + IIF(lcUncompressed == lcOriginal, "YES", "NO")
IF !(lcUncompressed == lcOriginal)
    EXIT
ENDIF
SET LIBRARY TO

****************************
*!* Example 7
****************************
*!* Demonstrates the callback functionality
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
ZipCallback("MyCallback()") && Start Event Handling - Any Function/Procedure/Method (in scope of course)
?ZipOpen("MyZip.zip", "C:\", .F.) && create zip file
?ZipFile("C:\MyFile.txt", .F.) && compress file into zip
?ZipClose() && done zipping
?UnzipQuick("C:\MyZip.zip", "C:\") && unzip contents of Test.zip to C:\
ZipCallback("") && Stop Event Handling
SET LIBRARY TO

*****************************
FUNCTION MyCallback()
    *****************************
    *!* Variables below are created on the fly
    *!* by the FLL when the ZipCallback feature is used

    *!* Depends on the value of nZipEvent
    ?cZipObjectName && Name of Zip, File, or Folder being processed

    *!* Events that fire MyCallback
    *!* 0 = Open Zip
    *!* 1 = Start Zip/Unzip of File
    *!* 2 = Read/Write File (nZipBytes will contain value of bytes read for event)
    *!* 3 - End Zip/Unzip of File
    *!* 4 - Folder Opened
    *!* 5 - Close Zip
    ?nZipEvent

    *!* Number of Bytes read (Event 3)
    ?nZipBytes

ENDFUNC

****************************
*!* Example 8
****************************
*!* Demonstrates how to use the UnzipAFileInfo()
*!* and UnzipAFileInfoByIndex() functions.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
UnzipOpen("C:\MyZip.zip")
UnzipGotoTopFile()
UnzipAFileInfo("laTestArray1")
UnzipClose()
showfileinfo(@laTestArray1)
?
UnzipOpen("C:\MyZip.zip")
UnzipAFileInfoByIndex("laTestArray2",2)
UnzipClose()
showfileinfo(@laTestArray2)
SET LIBRARY TO

FUNCTION showfileinfo(aFileInfo)
    LOCAL lnCounter
    LOCAL ARRAY aCaptions(13)
    aCaptions(1) = "File Name"
    aCaptions(2) = "Comment"
    aCaptions(3) = "Version"
    aCaptions(4) = "Version Needed"
    aCaptions(5) = "Flags"
    aCaptions(6) = "Compression Method"
    aCaptions(7) = "DateTime"
    aCaptions(8) = "CRC"
    aCaptions(9) = "Compressed Size"
    aCaptions(10) = "Uncompressed Size"
    aCaptions(11) = "Internal Attribute"
    aCaptions(12) = "External Attribute"
    aCaptions(13) = "Folder"
    FOR lnCounter = 1 TO 13
        ?aCaptions(lnCounter)
        ?aFileInfo(lnCounter)
        ?TYPE("aFileInfo(lnCounter)")
    ENDFOR
ENDFUNC

****************************
*!* Example 9
****************************
*!* Manipulate the global zipfile comment of a zip file.
****************************
SET LIBRARY TO LOCFILE("vfpcompression.fll")
ZipComment("C:\MyZip1.zip", "Hello") && add or replace a global comment to a zip file
ZipComment("C:\MyZip2.zip", "") && delete a global comment from a zip file
SET LIBRARY TO

>VFP Compression Documentation:

Function ZipString()

Signature: ZipString(cString[, nLevel])

Parameters:

cString - The character string you wish to compress

nLevel - The compression level to use which is 1 through 9 (1 is the fastest, while 9 is the best compression). The default value for this parameter is 6.

Return Value:

Character Data - the compressed version of cString.

Remarks:

This function is particularly useful in a client-server application given that strings of data (such as memo fields, character fields, and xml) can be compressed before sending them across the network and then extracted at the other end (using UnzipString).

Function ZipFileQuick()

Signature: ZipFileQuick(cFileName[, cPassword])

Parameters:

cFileName - The fully qualified file name (full path) of the file you wish to have compressed.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The zip file that this function creates will have the same file name as cFileName, with the extension as ".zip".

Function ZipFolderQuick()

Signature: ZipFolderQuick(cFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cFolderName - The full path to the folder you wish to have zipped.

cPassword - The password you wish to protect the zipped files with.

lIgnorePath - If you wish to ignore the relative path of the file into the zip file that is being created you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The zipfile that this function creates will have the same file name as cFolderName, with the extension as ".zip".

Function ZipOpen()

Signature: ZipOpen(cZipFileName[,cFolderName[,lAppend]])

Parameters:

cZipFileName - The file name or full path of the zip file you wish to create.

cFolderName - The full path of the folder in which you want cZipFileName created.

lAppend - If the zip file you are compressing to exists you can choose to append to it by passing .T. to this parameter. Defaults to .F..

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipOpen() is used in conjunction with the matching ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

Function ZipClose()

Signature: ZipClose()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipClose() must be called after issuing a ZipOpen(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

Function ZipFile()

Signature: ZipFile(cFileName[,lIgnorePath[,cPassword]])

Parameters:

cFileName - The file name or full path of the file you wish to compress.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFile() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Different passwords can be specified for different files and you can even selectively password protect files within the zip.

Function ZipFileRelative()

Signature: ZipFileRelative(cFileName[,cRelativePath[, cPassword]])

Parameters:

cFileName - The file name or full path of the file you wish to compress.

cRelativePath - The relative path you wish to have saved in the zip for this file. This allows you to set up the structure (relative paths) in the zip different from the actual relative paths of the files you are compressing.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFileRelative() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

Function ZipFolder()

Signature: ZipFolder(cFolderName[,lIgnorePaths[, cPassword]])

Parameters:

cFolderName - The full path to the folder you wish to compress.

lIgnorePaths - If you wish to ignore the relative path of the folder into the zip file that is being created you would pass .T. for this parameter. The default value for this parameter is .F. which means that paths will be respected.

cPassword - The password you wish to protect the zipped file with.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

ZipFolder() is used between calls to ZipOpen() and ZipClose(). The usual series of function calls would consist of creating/opening the zip file using ZipOpen, zipping files and/or folders using ZipFile/ZipFileRelative/ZipFolder, and then closing the zip file using ZipClose.

Function UnzipString()

Signature: UnzipString(cString)

Parameters:

cString - The compressed string you wish to uncompress.

Return Value:

Character Data - the extracted version of cString.

Remarks:

The string to be extracted must have been compressed with the ZipString() function or other compression function that is compatible with the compress or compress2 functions in zlib.

Function UnzipQuick()

Signature: UnzipQuick(cZipFileName, [cOutputFolderName[, lIgnorePaths[, cPassword]]])

Parameters:

cZipFileName - The fully qualified file name (full path) of the zip file you wish to have extracted.

cOutputFolderName - The full path to the folder you wish to extract the contents of the zip to.

cPassword - The password to use when unzipping the file.

lIgnorePaths - If you wish to ignore the relative paths that are contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative paths will be respected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

The file and folders in the zip file will be extracted into the same folder as the cZipFileName resides in.

Function UnzipOpen()

Signature: UnzipOpen(cZipFileName)

Parameters:

cZipFileName - The file name or full path of the zip file you wish to uncompress.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipOpen() is used in conjunction with the matching UnzipClose(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

Function UnzipClose()

Signature: UnzipClose()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipClose() must be called after issuing an UnzipOpen(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

Function Unzip()

Signature: Unzip([lIgnorePaths[, cPassword]])

Parameters:

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

Unzip() is used between calls to UnzipOpen() and UnzipClose() to uncompress the entire zip file. The files and folders contained in the zip file will be extracted to the same folder as the zip file resides in unless a call to UnzipSetFolder() has been previously issued. The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

Function UnzipTo()

Signature: UnzipTo(cOutputFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cOutputFolderName - The folder into which the zip file contents should be extracted.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipTo() is used between calls to UnzipOpen() and UnzipClose(). The functionality of this is similar to calling UnzipSetFolder() and then Unzip(). The usual series of function calls would consist of opening the zip file using UnzipOpen, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

Function UnzipFile()

Signature: UnzipFile(cOutputFolderName[, lIgnorePaths[, cPassword]])

Parameters:

cOutputFolderName - The folder into which the current file (cotained in the zip) should be extracted.

lIgnorePaths - If you wish to ignore the relative path of the current file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipFile() is used between calls to UnzipOpen() and UnzipClose() to extract the currently selected file contained in the zip file. UnzipFile() is used in conjunction with the UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

The cPassword is usually the same for all files within a zip, however it does not need to be the same. Just keep in mind that passwords can be specified for different files within a zip and when you are unzipping such an archive you will need to change the cPassword accordingly.

Function UnzipByIndex()

Signature: UnzipByIndex(nIndex[, cOutputFolderName[,lIgnorePaths, cPassword]]])

Parameters:

nIndex - The index number of the file to be extracted.

cOutputFolderName - The folder into which the zip file contents should be extracted.

lIgnorePaths - If you wish to ignore the relative path for this file that is contained in the zip file you would pass .T. for this parameter. The default value for this parameter is .F. which means that the relative path will be respected.

cPassword - The password to use when unzipping the file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipByIndex() is used between calls to UnzipOpen() and UnzipClose() to extract a file by the position (index) it holds in the zip file. UnzipByIndex() is used in conjunction with the UnzipFileCount function. You can think of the contents of a zip file as records in a table. In this sense UnzipFileCount would give you the record count for the table and the UnzipByIndex function be used to extract a particular file by record number.

Function UnzipFileCount()

Signature: UnzipFileCount()

Parameters: None

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipFileCount() is used between calls to UnzipOpen() and UnzipClose() to retrieve the number of files that are contained in the zip file. It does not actually extract anything. UnzipFileCount() is used in conjunction with the UnzipByIndex function. You can think of the contents of a zip file as records in a table. In this sense UnzipFileCount would give you the record count for the table and the UnzipByIndex function be used to extract a particular file by record number.

Function UnzipSetFolder()

Signature: UnzipSetFolder(cOutputFolderName)

Parameters:

cOutputFolderName - The folder into which the zip file contents should be extracted.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipSetFolder() is used between calls to UnzipOpen() and UnzipClose() to set the output folder for extracted zip contents. It does not actually extract anything. The usual series of function calls would consist of opening the zip file using UnzipOpen, calling UnzipSetFolder to set the output folder, uncompressing files and/or folders using Unzip/UnzipTo/UnzipByIndex/UnzipFile, and then closing the zip file using UnzipClose.

Function UnzipGotoTopFile()

Signature: UnzipGotoTopFile([cExtension])

Parameters:

cExtension - The file extension to use as a filter for file type. All other file types will be ignored and only the first file of the type specified will be selected in the zip file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoTopFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoTopFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the first record of a particular file type. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

Function UnzipGotoNextFile()

Signature: UnzipGotoNextFile([cExtension])

Parameters:

cExtension - The file extension to use as a filter for file type. All other file types will be ignored and only the next file of the type specified will be selected in the zip file.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoNextFile() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file. UnzipGotoNextFile() is used in conjunction with the UnzipFile function to extract a particular file from the zip. By using the cExtension optional parameter you can select the next record of a particular file type. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

Function UnzipGotoFileByName()

Signature: UnzipGotoFileByName(cFileName[, lIgnoreFilePath])

Parameters:

cFileName - The file name of the file you wish to select in the zip file contents. You can specify a relative path as well to narrow down the search.

lIgnoreFilePath - If you wish to just find a file of a particular name in the zip file you can pass .T. for this parameter and the relative path of the file will be ignored. The first matching file of the name specified in cFileName will be selected in the zip contents.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoFileByName() is used between calls to UnzipOpen() and UnzipClose() to select a particular file in the contents of the open zip file by file name and/or relative path. UnzipGotoFileByName() is used in conjunction with the UnzipFile function to extract a particular file from the open zip file. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

Function UnzipGotoFileByIndex()

Signature: UnzipGotoFileByIndex(nIndex)

Parameters:

nIndex - The index number of the file to be selected.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

UnzipGotoFileByIndex() is used between calls to UnzipOpen() and UnzipClose() to select a particular file by the position it physically holds in the contents of the open zip file. UnzipGotoFileByIndex() is used in conjunction with the UnzipFile function to extract a particular file from the zip file contents. You can think of the contents of a zip file as records in a table. In this sense UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions are used to move the record pointer and the UnzipFile function is used to extract the file that the record pointer is currently on.

Function UnzipAFileInfoByIndex()

Signature: UnzipAFileInfoByIndex(cArrayName, nIndex)

Parameters:

cArrayName - Name of the VFP array to be created with file information in it.

nIndex - The index number of the file you want to return information about.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Creates an array with 13 rows (elements) in it. The rows contain various pieces of information regarding the file that is held in the zip file at nIndex. The following table describes the contents and data type of each row in the array:

Row	Array Content	Data Type
1	File Name	Character
2	Comment	Character
3	Version	Numeric
4	Version Needed	Numeric
5	Flags	Numeric
6	Compression Method	Numeric
7	DOS Date	Datetime
8	CRC	Numeric
9	Compressed Size	Numeric
10	Uncompressed Size	Numeric
11	Internal Attribute	Numeric
12	External Attribute	Numeric
13	Folder	Logical

Remarks:

The array that is created will have whatever name was specified by cArrayName. Should the array already exist it will release it and recreate it. UnzipAFileInfoByIndex() is used between calls to UnzipOpen() and UnzipClose() to show information about a particular file. The file is referred to by the position it physically holds in the contents of the open zip file. You can think of the contents of a zip file as records in a table. In this sense the UnzipAFileInfoByIndex function is used to refer to and retrieve information about a particular record number in the zip file.

Function UnzipAFileInfo()

Signature: UnzipAFileInfo(cArrayName)

Parameters:

cArrayName - Name of the VFP array to be created with file information in it.

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Creates an array with 13 rows (elements) in it. The rows contain various pieces of information regarding the currently selected file in the zip. The following table describes the contents and data type of each row in the array:

Row	Array Content	Data Type
1	File Name	Character
2	Comment	Character
3	Version	Numeric
4	Version Needed	Numeric
5	Flags	Numeric
6	Compression Method	Numeric
7	DOS Date	Datetime
8	CRC	Numeric
9	Compressed Size	Numeric
10	Uncompressed Size	Numeric
11	Internal Attribute	Numeric
12	External Attribute	Numeric
13	Folder	Logical

Remarks:

The array that is created will have whatever name was specified by cArrayName. Should the array already exist it will release it and recreate it. UnzipAFileInfo() is used between calls to UnzipOpen() and UnzipClose() to show information about a particular file. Use the UnzipAFileInfo function in conjunction with UnzipGotoTopFile, UnzipGotoNextFile, UnzipGotoFileByName, and UnzipGotoFileByIndex functions to return information regarding a particular file contained in the open zip file. You can think of the contents of a zip file as records in a table. In this sense the UnzipAFileInfo function is used to refer to and retrieve information about the record that the record pointer is currently on within the zip file.

Function ZipCallback()

Signature: ZipCallback(cFunction)

Parameters:

cFunction - A string denoting a function, procedure, or method that you want fired whenever a zip event occurs, such as "MyCallback()".

Return Value: None

Events:

When one of the following zip events occurs the function/procedure/method specified by the cFunction parameter will be called. cZipObjectName, nZipEvent, and nZipBytes are private variables created on-the-fly by the FLL. They will contain the values specified in the table below.

Event Description	cZipObjectName (character)	nZipEvent (numeric)	nZipBytes (numeric)
Zip Opened	Name and path of zip file	0	N/A
Zip/Unzip File Start	Name and path of file being zipped/unzipped	1	N/A
Zip Read or Unzip Write	Name and path of file being zipped/unzipped	2	Number of bytes currently being read or written
Zip/Unzip File End	Name and path of file being zipped/unzipped	3	N/A
Zip/Unzip Folder Opened	Name and path of folder being zipped/unzipped	4	N/A
Zip Closed	Name and path of zip file	5	N/A

Remarks:

Event handling is started as soon as you call ZipCallback and pass it the name of a function, procedure, or object method. ZipCallback provides a way for you to hook into the internal events happening inside of the VFPCompression FLL. nZipBytes reports the number of bytes currently being read during zip (2048 bytes at a time) or written during unzip (4096 bytes at a time) of an individual file. In order to turn off event handling simply call the ZipCallback with an empty length string, such as ZipCallback("").

Function ZipComment()

Signature: ZipComment(cZipFileName, cComment)

Parameters:

cZipFileName - The file name or full path to the zip file you wish to add, replace, or delete the comment on.

cComment - A string containing the comment (maximum of 255 characters)

Return Value:

None - returns .T. if successful or .F. if the operation has failed.

Remarks:

If a comment does not exist in the zip file, the string designated in cComment will be added. However, if a comment already exists in the zip file, the existing comment will be replaced with the cComment specified. This replacement functionality allows you to also delete an existing comment in a zip file by passing an empty string to the cComment parameter.

This weblog is sponsored by SweetPotato Software, Inc.

An Update for the VFPConnection Library

Craig Boyd — Sat, 29 Nov 2008 13:01:34 GMT

VFPConnection Library
I first introduced the VFPConnection.fll in an earlier blog post and the functionality it provided at the time was adequate for the task at hand. However, it didn't provide support for some of the features that members of the VFP Community wanted. Most of the enhancement requests I received from them centered around two things:

Support for SSL (HTTPS and FTPS)
Implementation of a Tracing/Debugging Mechanism

So, I've enhanced the FLL to provide additional functions and another callback parameter that seek to fulfill a portion of these two requests. There is certainly much more that can be done (and will be done) with this FLL in the future. For now I believe the additional features I've implemented warrant the release of an update. At the bottom of this blog entry, you'll find a download link for the updated FLL, some new sample use code, and new documentation that encompasses the additional functions and callback parameter.

What's New
I've added 6 new functions to handle communication via Secure Sockets Layer (SSL): FTPSGet(), FTPSPut(), FTPSToStr(), HTTPSGet(), HTTPSPUT(), HTTPSToStr(). I've also added a new parameter, cTraceCallback, to all of the FLL's functions. This new callback is especially useful when doing FTP/FTPS transfers as it reports on all of the traffic going back and forth between the client and server.

What's Next
I plan to add a bunch more FTP functionality and some facility for doing HTTP POSTs. I'm hopeful that those of you that download this library will take the time to provide me feedback and any suggestions you may have for further improving it. The update provided here is a testament to the fact that your feedback is valuable and an integral part of the improvement process for the stuff I provide to the VFP Community.

Until next time... Visual FoxPro Rocks!

PLEASE NOTE: An updated version of this FLL and documenation is available here.

VFPConnection FLL Download (395 KB approx.)

VFPConnection.FLL Sample Use Code:

CLEAR
SET LIBRARY TO (LOCFILE("vfpconnection.fll","FLL"))

*!* Uncomment any of the lines of code below, modify it to suit, and then execute the code.
*!* NOTE: The new trace parameter

*!* ?FILEGet("File:///C:\Source.txt", "C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* ?FTPGet("FTP://UserName:Password@somedomain.com/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* ?FTPSGet("FTPS://UserName:Password@somedomain.com:21/directory/Source.zip", "C:\Destination.zip", "MyProgress()", "MyTrace()")
*!* ?HTTPGet("http://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")
*!* ?HTTPSGet("https://www.somedomain.com/Source.htm", "C:\Destination.htm", "MyProgress()", "MyTrace()")

*!* ?FILEPut("C:\Source.txt", "File:///C:\Destination.txt", "MyProgress()", "MyTrace()")
*!* ?FTPPut("C:\Source.zip", "FTP://UserName:Password@somedomain.com/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* ?FTPSPut("C:\Source.zip", "FTPS://UserName:Password@somedomain.com:21/directory/Destination.zip", "MyProgress()", "MyTrace()")
*!* ?HTTPPut("C:\Source.htm", "http://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")
*!* ?HTTPSPut("C:\Source.htm", "https://www.somedomain.com/Destination.htm", "MyProgress()", "MyTrace()")

*!* ?FILEToStr("C:\Source.txt")
*!* ?FTPSTOSTR("FTPS://UserName:Password@somedomain.com:21/directory/Source.txt")
*!* ?HTTPSToStr("https://www.somedomain.com/Source.txt")

SET LIBRARY TO

***********************
FUNCTION MyProgress() && Callback from the FLL - can be used to track operation progress
***********************
?m.nConnectTotalBytes
?m.nConnectBytesSoFar
ENDFUNC

***********************
FUNCTION MyTrace() && Callback from the FLL - used to provide a detailed trace of the operation
***********************
    #DEFINE TYPE_TEXT 0
    #DEFINE TYPE_HEADER_IN 1
    #DEFINE TYPE_HEADER_OUT 2
    #DEFINE TYPE_DATA_IN 3
    #DEFINE TYPE_DATA_OUT 4
    #DEFINE TYPE_SSL_DATA_IN 5
    #DEFINE TYPE_SSL_DATA_OUT 6
    #DEFINE TYPE_END 7
?ICASE(m.nTraceDataType = TYPE_TEXT, "STATUS:", ;
     m.nTraceDataType = TYPE_HEADER_IN, "<RECV HEADER: ", ;
     m.nTraceDataType = TYPE_HEADER_OUT, ">SEND HEADER: ", ;
     m.nTraceDataType = TYPE_DATA_IN, "<RECV DATA: ", ;
     m.nTraceDataType = TYPE_DATA_OUT, ">SEND DATA: ", ;
     m.nTraceDataType = TYPE_SSL_DATA_IN, "<RECV SSL DATA: ", ;
     m.nTraceDataType = TYPE_SSL_DATA_OUT, ">SEND SSL DATA: ", ;
     m.nTraceDataType = TYPE_END, "END: ", "UNKNOWN: ")
??m.cTraceData
ENDFUNC

>>
VFPConnection.FLL Documenation:

Function FTPGet()

Signature: FTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()" >
Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FTPSGet() >
Signature: FTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()" >
Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function HTTPGet() >
Signature: HTTPGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a website.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>Function HTTPSGet() >
Signature: HTTPSGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to download a file from a a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>>Function FILEGet() >
Signature: FILEGet(cSourceURL, cDestination[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The full path and file name to the file you wish to copy.

cDestination - The full path and file name where you want the source file saved.

cProgressCallback – An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file from a local or remote location.

The format for the cSourceURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cSourceURL as “FILE:// C:\MyDir\MyFile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FTPPut() >
Signature: FTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FTPSPut() >
Signature: FTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cDestinationURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function HTTPPut() >
Signature: HTTPPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function HTTPSPut() >

Signature: HTTPSPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want uploaded.

cDestinationURL - The URL to where the file specified in cSource should be uploaded to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to upload a file to a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FILEPut() > >
Signature: FILEPut(cSource, cDestinationURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSource - The full path and file name of the file you want copied.

cDestinationURL - The full path and file name where the file specified in cSource should be copied to.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to copy a file to a local or remote location.

The format for the cDestinationURL parameter is slightly different than you might expect. In order to copy file C:\MyDir\MyFile.zip you would specify cDestinationURL as “FILE:// C:\MyDir\MyFile.zip”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FTPToStr() >
Signature: FTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file from an FTP site as a string.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTP://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>Function FTPSToStr()

Signature: FTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to return a string from.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Character Data - the contents of the file specified by cSourceURL

Remarks:

This function provides the ability to retrieve a file as a string from an FTP site that provides FTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

In order to specify port or login information you would simply include them in cSourceURL, such as “FTPS://myusername:mypassword@myftpsite.com:21/mydir/myfile.txt”.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>>>Function HTTPToStr()

Signature: HTTPToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file from a website as a string.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End.

>Function HTTPSToStr() >
Signature: HTTPSToStr(cSourceURL[, cProgressCallback[, cTraceCallback]])

Parameters:

cSourceURL - The URL to the file you wish to download.

cProgressCallback - An optional string denoting a function, procedure, or method that you want fired whenever a read/write occurs, such as "MyProgress()".

cTraceCallback - An optional string denoting a function, procedure, or method that you want fired whenever additional information regarding the status of the operation is available. Eample: "MyTrace()"

Return Value:

Logical - returns .T. if successful or .F. if the operation has failed.

Remarks:

This function provides the ability to retrieve a file as a string from a website that provides HTTP over Secure Sockets Layer (SSL). It should be noted that this function does not check the site's certificate for authenticity/validness nor does it compare the site to the identity specified by the certificate.

When the cProgressCallback is called 2 variables (nConnectTotalBytes and nConnectBytesSoFar) are created dynamically by the FLL. These variables can be used within the specified function, procedure, or method to determine the total size of the source file in bytes as well as the total progress of the operation (Percentage = 100 * nConnectBytesSoFar / nConnectTotalBytes).

When the cTraCallback is called 2 variables (nTraceDataType and cTraceData) are created dynamically by the FLL. The variable nTraceDataType specifies the type of operation that produced the information contained in cTraceData. The possible values for nTraceDataType are as follows: 0 = Text, 1 = Header In, 2 = Header Out, 3 = Data In, 4 = Data Out, 5 = SSL Data In, 6 = SSL Data Out, 7 = End. > >

This weblog is sponsored by SweetPotato Software, Inc.

Virtual Earth Class Library for Visual FoxPro

Craig Boyd — Thu, 27 Nov 2008 10:10:20 GMT

Virtual Earth
Billed as "...the integrated mapping, imaging, search, and data visualization platform", Microsoft's Virtual Earth (VE) is an awesome mapping service that can be consumed and manipulated using the VE Map contol and JavaScript. In order to get a feel for what VE is capabable of, head on over to the VE Interactive SDK and try some of the examples provided. There is plenty of documentation, blog entries and articles available online that provide general VE overviews and detail the specific features the service provides, so I won't spend a lot of time explaining what VE is and what it does. I want to explain enough so that you can understand the goals of the VFP Virtual Earth wrapper class library that I'm presenting in this blog entry. I figure you can do a few online searches if you're interested in a deeper or broader understanding of VE and its specific features.

Virtual Earth Map Control
In order to understand VE from a developer standpoint you'll need to be familiar with the Virtual Earth Map Control. The VE Map Control and the JavaScript classes/enumerations that make it up are provided via a web handler (.ashx file). I find it is more understandable to think of it as a library rather than a control. The VEMap class (which is part of the VE Map Control) is what I would consider the actual control that is seen within a web page. Perhaps I'm splitting hairs here, but I found it to be a helpful distinction in my mind when first starting to work with VE.

Creating Your First VE Web Page
It's pretty simple to add the VE Map Control to a web page and use it to instantiate an instance of the VEMap class. Here's the basic HTML needed in order to create such a page...

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>Virtual Earth</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <script type="text/javascript" src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>
        <script type="text/javascript">
            var map = null;
            function startVE()
            {
                map = new VEMap('myMap');
                map.LoadMap();
            }
            function cleanUp()
            {
                if (map != null) map.Dispose();
            }
        </script>
    </head>
    <body onload="startVE();" onunload="cleanUp();" style="margin: 0px">
        <div style="overflow: hidden; width: 100%; height: 100%;" id="myMap" />
    </body>
</html>

You should note that the first script tag specifies the web handler mapcontrol.ashx as the source. Also, note how an instance of VEMap is created using the body's onload and is eventually disposed of in the cleanUp() function via the body's onunload. In any event, it's pretty easy stuff given the results (go ahead and cut and paste that bit of code into an HTML file and view it in Internet Explorer).

What About Desktop Applications?
Obviously, given the architecture and heavy reliance on JavaScript, this stuff was made for web applications. But what about desktop applications that require geocoding of addresses, distance measurements, scheduling based on zones, or routing with turn-by-turn directions? I mean, Virtual Earth would work great if there was just some way to run an HTML page on a VFP form... Oh wait, Microsoft has provided us the WebBrowser control! Just drop that ActiveX control on a form and make a quick call to something like, Thisform.Olecontrol1.Navigate("file:///C:\VETest.html"). Looks like we're in business.

The only thing that's left to do after that is write all of the JavaScript code that interacts with the VE Map Control. Awesome! Except that... erm... you may not know very much JavaScript (even though you're a kick-butt VFP developer), and you may need VFP code to freely interact with the JavaScript objects (or vice versa), and how the heck do you get JavaScript to read your database where all of your addresses are stored? And... And...

Virtual Earth Wrapper for VFP
OK, so the previous section outlines the thought process that eventually lead to the class library that I built to tackle these problems. While working on a VFP project for a customer that involved VE, I looked at that list of classes and enumerations for the Virtual Earth Map Control version 6.2 and basically thought, "Wouldn't it be super cool if those were all VFP classes??!!".

I needed a class library (.vcx) wrapper for VE. This would contain all of the same classes (VFP equivalents) and a few super slick ways to commuicate and convert between VFP and JavaScript. With those in hand it would simply be a matter of hammering out the 5-10 thousand lines of code and comments to make it happen. I won't go into the particulars of everything I ended up doing in order to make this work (you can look in the class library's code yourself if you're interested), but I did end up using the JSON class I created to handle most of the conversions and transport (data interchange) between the two languages.

As you'll see in the download, the class library wrapper (virtualearth.vcx) is pretty much a carbon copy of the VE classes. So, most of the documentation and code that's online for VE is of benefit when using it. In addition to the virtualearth.vcx, I've also provided a sample project and form (see screenshot below), so you can try this stuff out right away. The sample project is also intended to provide a little more information regarding how to do some of the things that a developer might want to do with VE in a desktop application. I usually find that learning by example is one of the fastest ways to get up to speed on a technology I'm not very familiar with.

Special Thank You
Before I wrap this blog entry up, I want to express my appreciation for Marc Lyon's efforts. He provided me early feedback and testing for this class library. His enthusiasm for this project was also one of the driving forces behind my completing it as fast as I did.

I also want to thank my client (you know who you are) who has been kind enough to allow me to share this work with the VFP Community. You're about as generous and kind as they come.

What's Next
Just have fun with Virtual Earth in VFP and see if virtualearth.vcx is useful to you and your applications. In a perfect world, you'd report back to me with any bugs you find, create some examples of your own and blog about them, or seek to improve the library in some way. If you do improve virtualearth.vcx, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to follow any of the above suggestions.

Until next time... Visual FoxPro Rocks!

Download VirtualEarth.vcx and Sample (approx. 222 KB)

>>>
Figure 1: A sample form provided in the download. It gives developers a starting point when beginning to work with the virtualearth.vcx.

This weblog is sponsored by SweetPotato Software, Inc.

Visual FoxPro Grid Enhancements

Craig Boyd — Tue, 25 Nov 2008 00:00:52 GMT

The Visual FoxPro Grid Control
I've often been heard to say that Visual FoxPro's grid is one of the greatest controls ever devised. I still feel that way, but wouldn't it be nice if some of the functionality that our customers want implemented in the grid came stock? You know, features like: sorting, filtering, incremental search, saving user preferences, and exporting to Excel. It'd be even cooler if this type of functionality could be implemented on any Visual FoxPro grid (regardless of the recordsource) by simply dropping a class on a form, setting a single property and writing a single line of code. Well, that's what I have set out to create with the class I present in this blog entry.

First Shown at Southwest Fox 2008
At Southwest Fox 2008, I presented a session entitled "Creating a Professional VFP Application from Start to Finish" in which I showed an earlier version of GridExtras. I've improved on it since then, so if you attended Southwest Fox 2008 you may want to get the control and sample from here rather than the session download. For those of you that didn't attend Southwest Fox 2008 (you should have - it was a blast!), you can see the basic functionality provided by GridExtras in the screenshots provided at the bottom of this blog entry.

How to Use the Class
I've provided a sample.exe application in the download so you can try it out and see how it's implemented. However, the basic steps are:

Drop an instance of the gridextras onto your form or container (one gridextras for each grid you want to enhance).
Set the GridExtras' GridExpression property to a string that will evaluate at runtime to the grid you are enhancing - "Thisform.Grid1" is the default value for this property.
Call the GridExtras' Setup() method whenever your grid is ready to go. I have no way of knowing if you are setting the recordsource at runtime, or whether you are adding columns in code, so this method is provided as a way for you to control when GridExtras will begin interacting with the grid.

That's all there is to getting GridExtras up and running for a grid in your application. As I say, I've included a sample in the download, so if you have any questions about how this is done just review the sample or you can post a comment here on my blog and I'll do my best to answer it.

Other Properties of Note
There are a few other GridExtras properties you may want to take note of and use, such as:

CompanyName and ProductName - these properties are used to determine where to save the user's grid preferences file which is profile isolated (C:\Users\Craig\AppData\Roaming\MyCompany\MyProduct\gridprefs.tmp on Vista or  C:\Documents and Settings\Craig\Application Data\MyCompany\MyProduct\gridprefs.tmp on Windows XP)
AllowGridExport, AllowGridFilter, AllowGridPreferences, AllowGridSort - these properties allow you to turn certain features of the class off or on depending on your needs.
TemplateTable - this property determines where GridExtras looks for the gridextras.dbf which is used to save the grid templates the user creates (user can save their filters and sorts to be able to easily recreate them at a later time). This property may need to be set if you plan to keep the gridextras table out on a network path such as with the shared database folder for your application.

What's Next
Just have fun with GridExtras and see if it's useful to you and your applications. In a perfect world, you'd find some way to improve it (add additional export formats, provide a column lock feature, etc.). If you do improve GridExtras, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to do so.

Until next time... Visual FoxPro Rocks!

Download GridExtras and Sample (approx. 170 KB)

Figure 1: GridExtras provides sorting, incremental search, and filtering capabilities to any Visual FoxPro grid.

Figure 2: GridExtras has additional features such as the ability to go semi-transparent and the ability to save the user's preferences (column order and width).

Figure 3: In addition to the features provided by GridExtras through a grid's column headers, there is also an icon added to the bottom right of the grid that allows the user to access the "Grid Templates and Export" screen seen in Figure 4.

Figure 4: The grid templates help the user save grid views so they can recreate them quickly in the future. The export feature of GridExtras can create XLS, XLSX, XLB, and XLM Excel formats. The grid's header captions are used to name the Excel columns when data is exported.

This weblog is sponsored by SweetPotato Software, Inc.

JSON for Visual FoxPro

Craig Boyd — Mon, 24 Nov 2008 12:38:28 GMT

What is JSON?
If you are unfamiliar with JSON, you can dig into the particulars about it here and here. The short explanation is that JSON provides a format for serializing and deserializing variables, arrays, and class instances. For those of you that may not know what serializing and deserializing are, think of serializing as turning a cursor into XML and then think of deserializing as turning XML back into a cursor. Basically the process of turning an instance of MySomething into a string and then turning that string back into an instance of the same MySomething.

Now, besides the obvious advantages of being able to serialize and deserialize VFP values and objects (persisting them on disk or passing them across the wire, just to name a couple), it becomes really useful when you find that you have to interact with Javascript from your Visual FoxPro application. I ran into this while working with Virtual Earth in a webbrowser control (more on that in an upcoming blog entry). I wanted to use JSON as part of my solution because it would allow me to easily move values, instances, and data back and forth between Visual FoxPro and the Javascript that was running inside a page being displayed in the webbrowser control. I could have done without it, but it's a lot more slick when using JSON.

JSON for VFP
If you visited the first "here" in my first paragraph in the section above you may have noted that they have a rather impressive list of languages that provide support, in some manner, for JSON at the bottom of the page. You may have also noted that Visual FoxPro was absent from that list. Now, that doesn't mean that no one has ever done this sort of thing before. In fact, Rick Strahl provides VFP/JSON support through his wwJSONSerializer class and FoxWeb provides similar functionality through it's fwJSON object. And, here in this blog entry, I'm going to provide you with another class that provides JSON support. So, hopefully someday we can get this class and the others listed on the json.org site (anyone know who to call or write to?).

Why Another JSON Class?
So, if Rick and FoxWeb already provide classes, it begs the question, "Why did I decide to write one too?". Well...

When I started working on this I didn't know that Rick even provided such a class in web connect. As for FoxWeb, I've never used it, so I don't know what their object does. Heck, for all I know there are other classes out there besides these two. If you know of any others, please feel free to comment on this blog entry with a link.
My JSON class provides additional support for some things when compared to the functionality of wwJSONSerializer:

Multi-dimensional array support
Replacer support on stringify
Reviver support on parse
Beautification/indetation support
Performance enhancements via FLL
A few other things, but those are the main ones

The implementation of my JSON class is patterned after json2.js (by Douglas Crockford), which means:

The main methods are Stringify() and Parse()
It supports datetimes in ISO8601 format (other formats available)
Provides the same default escaping of characters (other modes available).

Because I wanted to try my hand at this?

There's no better way that I know of to learn something than to write a wrapper or even a class that directly interacts with another library or API. So, I wrote a top-notch JSON class library. I am using it in a production project at this end (my customer was kind enough to give me permission to share it) and I am blogging about it in the hopes some of you may find it useful.

How to Use the JSON Class
In the class, I have provided lots of comments in the code to help document this thing. Also, provided in the download is a jsontests.prg that provides some sample use code you can look at to get started. For the sake of blog brevity... in order to serialize a Visual FoxPro object to JSON you'd do the following:

m.loJSON = CREATEOBJECT("JSON")
SET CLASSLIB TO (LOCFILE("JSON.VCX", "VCX", "Locate JSON Class Library")) additive
m.loObjectIn = CREATEOBJECT("Custom"
m.lcObjectJSON = m.loJSON.Stringify(m.loObjectIn, null, CHR(9))
?m.lcObjectJSON

...and then to deserialize that JSON string you'd do this:

m.loObjectOut = m.loJSON.Parse(m.lcObjectJSON)
?m.loObjectOut.Class

As I say, the code is heavily commented (so check it out) and I'll be doing a blog entry in the near future regarding a Virtual Earth class library I've written for VFP that shows some real world uses for JSON within VFP.

Special Thank You
I sincerely appreciate the efforts of those of you that have already been providing valuable feedback, such as Steven Black and Marc Lyon. Also, Rick Strahl, who provided help and sage advice to me via Twitter as I worked through the particulars of this class. It's always nice to have someone advising you who has already "been there, done that".

What's Next
I'm hopeful that those of you that download this class will take the time to provide me feedback and any suggestions you may have for further improving it.

Until next time... Visual FoxPro Rocks!

Download the JSON class library (approx. 52 KB)

The download contains the JSON class in both VCX and PRG format. Use whichever one you are more comfortable with (they are the same).

>>

This weblog is sponsored by SweetPotato Software, Inc.

Professional Error Handling for VFP Applications

Craig Boyd — Mon, 24 Nov 2008 11:07:36 GMT

Same Old, Same Old
Far too often developers will either not implement error handling in their applications (allowing VFP's default error handler to prevail) or they will display a simple messagebox containing a few pieces of error information such as the values returned from Visual FoxPro's Error(), Message() and Lineno() functions. In either case, this type of error handling is usually woefully inadequate. Not only are these approaches of little use to the user, it is probably disconcerting (if not a little frightening) to them. The possible end result of these approaches: bugs go unreported, error information is not captured, and the user's overall confidence in the application is shaken.

A Possible Approach to Error Handling
At Southwest Fox 2008, I presented a session entitled "Creating a Professional VFP Application from Start to Finish" in which I showed the error handler that I use in a number of applications I have developed. That error handler is presented here as one possible approach you can take when implementing error handling in your Visual FoxPro applications. There is sure to be room for improvement, but the state informaiton it gathers is pretty extensive and I've found that most users find the error screen (see screen shots below) to be non-threatening/reassuring when exceptions arise.

How to Use the Error Handler
In order to implement the error handler in your own applications, you'll need the functions and the ON ERROR command that are in the main.prg of the sample application (provided in the download below). You'll also want to include the issues.scx form in your project and set the MyCompany, MyProduct, MyTechEmailAddress, and MyTechPhoneNumber properties of the issues form with your information. That's about all there is to it. I have included an FLL with the sample, but this is merely used to facilitate the transmittal of the error information via email. If you implement another method of transmission (such as a post to a Web Connection web application), then you needn't include the FLL.

To try the error handler out you can download the sample below and, after setting the issues form properties as noted above, simply build the project provided and run the executeable you've built. A form is provided that allows you to submit an issue manually as a customer would and also to throw an error to see how the error handler works in an exception situation.

Due Credit
Most of the code that you'll find in the main.prg for collecting error information came from the book "Special Edition Using Visual FoxPro 6". And, the code that is used to terminate the process after the exception has occured is from work done by Doug Hennig. So, special thanks to those two sources.
>
What's Next
Just have fun with the error handler and see if it's useful to you and your applications. In a perfect world, you'd find some way to improve it (add screenshot ability, refactor the code, etc.). If you do improve the error handler, I'd appreciate it if you would contact me and share the improvements you've implemented. Thank you in advanced to those of you that decide to do so.

Until next time... Visual FoxPro Rocks!

Download Error Handling Sample (approx. 41 KB)

Figure 1: The screen the user sees when an exception occurs.

Figure 2: Respecting the user's privacy, they are allowed to view what the error report contains before it is sent.

Figure 3: The screen also allows the user to provide additional information before submitting the error report.

This weblog is sponsored by SweetPotato Software, Inc.