To obtain information about the files in the patch package, as well as add or remove individual files, the Package control makes the contents of the package available through its Files property. This property returns a PackageFiles collection which is a collection of all of the files currently in the package. Each member of the collection is represented as a PackageFile object.

The PackageFiles collection exposes two properties, Item and Count. The Item property (the default property for the collection) returns a PackageFile object which refers to a specific file in the package. The Count property returns the number of files currently in the collection. There are two ways to access the files in a patch package. One is to use the Count property and a For..Next loop to iterate through the collection, such as this:

For nIndex = 0 To Package1.Files.Count – 1
    If Package1.Files(nIndex).FileName = strFileName Then
        ' Do something with the file
    End If
Next

Note that the collection is 0-based which means the collection's index begins with the number 0 (versus a 1-based collection). Another method to access the files in a package is to use a For Each..Next loop such as this:

Dim File As PackageFile

For Each File In Package1.Files
    If File.FileName = strFileName Then
        ' Do something with the file
    End If
Next

In addition to iterating through the PackageFiles collection, a specific file can also be referenced directly by name. For example:

Dim File As PackageFile

Set File = Package1.Files("Programs\Widget.exe")
If (File.Flags And apFileVersionInfo) > 0 Then
    ' This file has version information
End If

An important thing to keep in mind, however, is that this method is only reliable for those packages which do not contain multiple versions of a file. If a file is referenced by name in such a package, the first file that matches the name, regardless of the target platform or version, is returned. To find a specific file, it is recommended that the application use the Package control's Find method instead.

The Package control's Find method returns a PackageFiles collection which matches a given search criteria. The method has three arguments, all of which are optional. The first is the name of the file to find and this name may include wildcards. If no name is specified, then all files in the package are returned which match the other search criteria. The second argument is a numeric value which specifies the target platform for the file. The third argument specifies any options for performing the search. Here is an example of how the Find method could be used:

Dim Files As PackageFiles
Dim File As PackageFile

Set Files = Package1.Find("*.exe", apPlatformWinNT, apRecursiveFind)

For Each File in Files
    If (File.Flags And apFileVersionInfo) > 0 Then
        ' This program has version information
    End If
Next

In this example, the Find method will return a collection of all of the executable programs in the package which are targeted for the Windows NT or Windows 2000 platforms. It then iterates through each file in the collection to determine if the file has version information available.

An important consideration is that when you create another instance of a PackageFiles collection, such as when using the Find method, any changes made to the collection (such as changing the name of a file) are immediately made in the package itself. This in turn also alters the collection returned by the Package control's Files property. For example, consider a package which consists of 10 files.

The Package1.Files.Count property would return a value of 10. Then, the Find method is used to return a collection of just the executable files in the package. Let's say that there are a total of 4 executable programs in the package. That means that the Count property for the collection returned by the Find method would return a value of 4. Now, if one of the executables in the collection is deleted, the count drops to 3. This would also immediately be reflected in the collection returned by the Files property. In other words, Package1.Files.Count would now have a value of 9. However, if there was another collection that was created by using the Find method which contains all of the text files in the package, its file count would not change. Because of the complexities involved with maintaining different collections which represent different "views" of a given package, it is recommended that applications do not keep a reference to a collection object that is no longer being used by the current function or subroutine. Instead, each time the application needs to reference the PackageFiles collection, it should use the Files property or the Find method, and immediately release the collection object when it is finished with it. To ensure that a given collection refers to the current contents of the package, use the Refresh method in the PackageFiles object.

The Store method in the PackageFiles collection object is used to store an individual file in a package. As with creating an individual patch file, a reference file and an updated version of the file is provided along with a set of options. To store only the differences between two files, both a reference and updated version of a file must be specified. However, it is possible to store the entire contents of a file by omitting the reference file. This tells the Store method that a previous version of the file does not exist, and the complete file should be stored in the package. This is similar in concept to adding a file to a Zip archive.

Another possibility is to specify a file as a reference file but omit the updated file name. This tells the Store method that the file exists in the original version but does not exist in the updated version. In this case, information about the file is stored in the package but not the actual file data. When the package is applied, the file is removed from the target system.

One additional feature of using the Store method is the ability to specify an alternate file name for the file on the target system. In the previous examples, the name of the files stored in the package are based on the file names as found in the specified directories. However, there may be cases where two versions of the same file have different names. For example, one file may be named Widgets10.exe and the later version may be named as Widgets20.exe. In this case, the Store method can be used to store the differences between the two files but when it is applied on the target system, the file name Widgets.exe would be used.

The Delete method in the PackageFiles collection object is used to delete all of the files in the specified collection. This can be useful when used in conjunction with the Find method to delete a set of files which match a given criteria. Note that if the Delete method is used with the collection returned by the Files property (in other words, calling Package1.Files.Delete), all files in the package will be deleted. This method should be used with caution. Once a file has been deleted from the package, it cannot be recovered.