# Names in IStorage

This is the most complex interoperability issue. In the IPropertySetStorage interface, property sets are identified with FMTIDs, but in IStorage, they are named with strings with a maximum length of 32 characters.

To accomplish this mapping, the first task is to establish a mapping between FMTIDs and strings. Converting in the one direction, you have a FMTID, and need a corresponding string name. First, check whether the FMTID is one of a fixed set of well-known values, and use the corresponding well-known string name if so:

FMTID | String Name | Semantic
F29F85E0-4FF9-1068-AB91-08002B27B3D9 | “\005SummaryInformation” | OLE2 summary information
D5CDD502-2E9C-101B-9397-08002B2CF9AE D5CDD505-2E9C-101B-9397-08002B2CF9AE | “\005DocumentSummaryInformation” | Office document summary information and user-defined properties.

Note The DocumentSummaryInformation property set is special in that it contains two sections. Multiple sections are not permitted in any other property set. This property set is described in more detail in Appendix B, OLE Serialized Property Set Format.

The first was defined as part of OLE; the second one was defined by Microsoft Office.

Otherwise, algorithmically form a string name in the following way. First, convert the FMTID to little-endian byte order if necessary. Then, take the 128 bits of the FMTID and consider them as one long bit string by concatenating each of the bytes together. The first bit of the 128 bit value is the least significant bit of the first byte in memory of the FMTID; the last bit of the 128 bit value is the most significant bit of the last byte in memory of the FMTID. Extend these 128 bits to 130 bits by adding two zero bits to the end. Next, chop the 130 bits into groups of five bits; there will be 26 such groups. Consider each group as an integer with reversed bit precedence. For example, the first of the 128 bits is the least significant bit of the first group of five bits; the fifth of the 128 bits is the most significant bit of the first group. Map each of these integers as an index into the array of thirty-two characters:

ABCDEFGHIJKLMNOPQRSTUVWXYZ012345

This yields a sequence of 26 Unicode characters that uses only uppercase characters and numerals. Note that no two characters in this range compare equally in a case-insensitive manner in any locale. The final string is the concatenation of the string “\005” onto the front of these 26 characters, for a total length of 27 characters.

The following code illustrates one way to map from FMTID to property string:

    #define CBIT_BYTE        8
    #define CBIT_CHARMASK    5
    #define CCH_MAP          (1 << CBIT_CHARMASK)    // 32
    #define CHARMASK         (CCH_MAP - 1)           // 0x1f

    CHAR awcMap[CCH_MAP + 1] = "abcdefghijklmnopqrstuvwxyz012345";

    WCHAR MapChar(ULONG i) {
        return((WCHAR) awcMap[i & CHARMASK]);
        }

    VOID GuidToPropertyStringName(GUID *pguid, WCHAR awcname[]) {
        BYTE *pb = (BYTE *) pguid;
        BYTE *pbEnd = pb + sizeof(*pguid);
        ULONG cbitRemain = CBIT_BYTE;
        WCHAR *pwc = awcname;

        *pwc++ = ((WCHAR) 0x0005);
        while (pb < pbEnd) {
            ULONG i = *pb >> (CBIT_BYTE - cbitRemain);
            if (cbitRemain >= CBIT_CHARMASK) {
                *pwc = MapChar(i);
                if (cbitRemain == CBIT_BYTE && *pwc >= L'a' && *pwc <= L'z') {
                    *pwc += (WCHAR) (L'A' - L'a');
                    }
                pwc++;
                cbitRemain -= CBIT_CHARMASK;
                if (cbitRemain == 0) {
                    pb++;
                    cbitRemain = CBIT_BYTE;
                    }
                }
            else {
                if (++pb < pbEnd) {
                    i |= *pb << cbitRemain;
                    }
                *pwc++ = MapChar(i);
                cbitRemain += CBIT_BYTE - CBIT_CHARMASK;
                }
            }
        *pwc = L'\0';
        }

Converters of property string names to GUIDs should accept lowercase letters as synonymous with their upper case counterparts. The following example shows one way to map from the property string to a FMTID:

    ULONG
    PropertySetNameToGuid(
        IN ULONG cwcname,
        IN WCHAR const awcname[],
        OUT GUID *pguid)
    {
        ULONG Status = ERROR_INVALID_PARAMETER;
        WCHAR const *pwc = awcname;

        if (pwc[0] == WC_PROPSET0)
        {
            //Note: cwcname includes the WC_PROPSET0, and
            //sizeof(wsz…) includes the trailing L’\0’, but
            //the comparison excludes both the leading
            //WC_PROPSET0 and the trailing L’\0’.

            if (cwcname == sizeof(wszSummary)/sizeof(WCHAR) &&
                wcsnicmp(&pwc[1], wszSummary, cwcname - 1) == 0)
            {
                *pguid = guidSummary;
                return(NO_ERROR);
            }

            if (cwcname == CWC_PROPSET)
            {
                ULONG cbit;
                BYTE *pb = (BYTE *) pguid - 1;

                ZeroMemory(pguid, sizeof(*pguid));
                for (cbit = 0; cbit < CBIT_GUID; cbit +=
                CBIT_CHARMASK)
                {
                    ULONG cbitUsed = cibt % CBIT_BYTE;
                    ULONG cbitStored;
                    WCHAR wc;

                    if (cbitUsed == 0)
                    {
                        pb++;
                    }
                    wc = *++pwc - L’A’;        //assume uppercase
                    if (wc > CALPHACHARS)
                    {
                        wc += (WCHAR) (L’A’ - L’a’)’ //try lowercase

                        if (wc > CALPHACHARS)
                        {
                            wc += L’a’ - L’0’ + CALPHACHARS; //must
                                                          be a digit
                            if (wc > CHARMASK)
                            {
                                goto fail;       //invalid character
                            }
                        }
                    }
                    *pb |= (BYTE) (wc << cbitUsed);
                    cbitStored = min(CBIT_BYTE - cbitUsed,
                    CBIT_CHARMASK);
                    //If the translated bits wouldn’t fit in the
                      current byte

                    if (cbitStored < CBIT_CHARMASK)
                    {
                        wc >>= CBIT_BYTE - cbitUsed;
                        if (cbit + cbitStored == CBIT_GUID)
                        {
                           if (wc !+0)
                           {
                               goto fail;        //extra bits
                           }
                           break;
                        }
                        pb++;
                        *pb |= (BYTE) wc;
                    }
               }
               Status = NO_ERROR
          }
        }
    fail:
        return(Status);
    }

When attempting to open an existing property set (in IPropertySetStorage::Open) the (root) FMTID in hand is converted to a string as depicted above. If an element of the IStorage of that name exists, it is used. Otherwise, the open fails.

When creating a new property set, the above mapping determines the string name used.