IFSMgr_MetaMatch

IFSMgr_MetaMatch(
 string_t pUniPattern,
 string_t pUniName,
 int matchSem
 )

This service provides meta-character pattern matching which is needed by FSDs when searching for files. There are a number of different meta-matching semantics that are provided. The caller should specify the appropriate semantics based on the kind of meta-matching desired. All FSDs should use this service to search for files so that the entire system works consistently. Besides, if the meta-matching semantics are changed at a later point of time, the FSDs can work unchanged with the new semantics. This service takes care of both single and double byte character sets, so FSDs do not need to do any localization work.

There are three possible name formats that can be passed in under different situations to do meta-matching. All of them use the unicode character set. These are as follows:

FCB Name Format:
This format refers to a name or pattern as it occurs in a DOS directory entry. It consists of a "primary" component that is always 8 unicode characters long and an "extension" component that is always 3 unicode characters long. If necessary, primary or extension components are "right padded" with unicode space characters until they meet their respective length requirements. There is no intervening dot character between primary and extension components. In this format the routine assumes that both the name and pattern are upcased unicode. If the name was obtained from the media in OEM and was converted to unicode it is in upcased form, because it was stored that way. The IFS manager always passes patterns in upcased unicode form.
8.3 Name Format:
This format refers to a name or pattern as it occurs when a name is passed to a DOS name-based file I/O function (DOS FCB-style functions are excluded for the purposes of this definition). It consists of a "primary" component that is at least 1 but 8 or fewer unicode chars long, and an "extension" component that is 0 to 3 unicode chars long. If a name has an extension, there is one intervening dot character between the primary and extension component. If the name has no extension, there is no dot character after the primary component. The IFS manager will never pass an 8.3-format name with a trailing dot.
Long Name Format:
This format refers to a name or pattern as it occurs when a name is passed to the new DOS long-name-based file I/O functions. Such a name is just a unicode character string. They have no extension per-se. The dot character in such a name is treated just like any other character. Note that an 8.3-format name is just a special case of a long-format name, in that only 1 dot character is allowed. The IFS manager will never pass a long-format name with a trailing dot. The IFS manager can, however, pass a long-format pattern with a trailing dot if and only if the pattern contains meta characters. See below for the reason this is done.

There are a number of different meta-matching semantics that can be applied. There are also certain special rules about how names in the different formats are treated under the different meta-matching semantics. The scenarios an FSD will encounter while doing meta-matching and the appropriate parameters and name formats to use for each of these are described below:

Short Name API Matching Short Names From Media:
This service should be called with UFLG_DOS set. If there are meta-characters present in the pattern, UFLG_META must also be passed in. This will yield DOS compatible matching rules. Both the pattern and the name should be in unicode FCB name format whenever UFLG_DOS is set.
Short Name API Matching Long Names From Media:
This is not supported by this service. If an FSD wants to support this, it will have to figure out its own rules to perform the appropriate mappings. In general, it is not recommended that FSDs support this. For example, the FAT file system FSD provides shortname aliases for each long name and matches these short names on short name APIs to circumvent this issue.
Long Name API Matching Short Names From Media:
This service should be called with UFLG_NT set. If there are meta-characters present in the pattern, UFLG_META should also be passed in. In this case, the pattern can be anything allowed on the long-name APIs. However, the short name should be in 8.3-format (not FCB-format) and in the unicode character set. There are, however, certain special quirks in DOS that create complications while matching short names. These are described below.
DOS has name matching idiosyncrasies with respect to short names (that is, 8.3 format) that do not have an "extension" and how they must be matched with patterns containing embedded or trailing dots. The following rule must be observed in order to get DOS compatible match behavior when this service is called from a long name API which is matching names which are stored on media in 8.3 format (that is, as short names). The rule is true irrespective of whether the matching pattern has meta characters in it or not.
RULE: For this special case, we make a distinction between the following two kinds of short names:

  1. Having no dots in the name at all: This is the case of a short name with a primary component only.
  2. An embedded dot. The name has a dot but the last char in the name is not a dot. This is the case of a short name with both primary and extension components.
If the short name to be matched has an embedded dot, then nothing needs to be done to the name. The match can be done directly by calling this service. If the short name to be matched does not have a dot and the matching pattern has a dot, then append a trailing dot to the short name before calling this service.
Following this rule will yield DOS and NT compatible match results when using long name APIs to match short names retrieved from the media. The IFS manager passes a bit flag to FSDs indicating whether a matching pattern has a dot in it. This can be used by the FSDs to easily construct a name that can be correctly matched with a pattern.
Long Name API Matching Long Names From Media:
This service should be called with UFLG_NT set. If there are meta-characters present in the pattern, UFLG_META should also be passed in. In this case, both the pattern and the name can be anything allowed on the long-name APIs. Long-name APIs matching long names have no quirks. In long names, dots are just another character and are not accorded any special treatment. Dots are stored in long names as just another character. There is no need to add or remove dots from a long name prior to calling this service to match them.

pUniPattern
Supplies the matching pattern in unicode in the appropriate name format, as discussed above.
pUniName
Supplies the filename in unicode to be matched against the pattern. The name should be in the appropriate format, as discussed above.
matchSem
Supplies flags that determine the matching semantics to be used.
Meta-Matching Semantics Flags:  
UFLG_NT Matching follows strict NT semantics. These are the semantics used for matching long names on the long-name APIs.
UFLG_DOS Matching follows strict DOS semantics. These are the semantics used for matching short names on the short-name APIs. This refers to the 11 character fixed-length DOS FCB format.
UFLG_NT_DOS Matching follows NT semantics with certain exceptions applied to the strict regular expression matching that UFLG_NT implements. Exceptions to regular expression matching are applied, like assuming a name which has no dots will match a pattern which fully matches the name but ends in a "?" or ends in a "*.*" or ends in a ".*". If neither UFLG_NT or UFLG_NT_DOS is specified, the matching defaults to DOS semantics.
UFLG_META The matching pattern contains meta-characters.