//
// Copyright (c) Microsoft Corporation.  All rights reserved.
//
//
// This source code is licensed under Microsoft Shared Source License
// Version 1.0 for Windows CE.
// For a copy of the license visit http://go.microsoft.com/fwlink/?LinkId=3223.
//
/*++


Module Name:

    stream.c

Abstract:

    This file contains routines for manipulating streams.

Revision History:

--*/

#include "fatfs.h"

/*  OpenStream - Open/create stream
 *
 *  ENTRY
 *      pvol - pointer to VOLUME
 *      clusFirst - first cluster of stream (the search criteria)
 *      psid - pointer to SID, NULL if none
 *      pstmParent - pointer to parent DSTREAM (NULL if none/unknown)
 *      pdi - pointer to DIRINFO (NULL if none/unknown)
 *      dwFlags - one or more OPENSTREAM_* flags (eg, OPENSTREAM_CREATE, OPENSTREAM_REFRESH)
 *
 *  EXIT
 *      pointer to DSTREAM if successful (and critical section left held),
 *      NULL if not (ie, out of memory)
 *
 *  NOTES
 *      If clusFirst is UNKNOWN_CLUSTER, then psid becomes the search criteria.
 *
 *      Streams for data that is not cluster-mapped (eg, FAT, root directory)
 *      must be completely contiguous;  their RUN info must be set to match
 *      the size of the stream, so that ReadStream will always call directly
 *      to ReadStreamBuffer without attempting to call UnpackRun (which knows
 *      only how to deal with cluster-mapped data).
 */

PDSTREAM OpenStream(PVOLUME pvol, DWORD clusFirst, PDSID psid, PDSTREAM pstmParent, PDIRINFO pdi, DWORD dwFlags)
{
    PDSTREAM pstm;
    PFILELOCKSTATE pFileLockState;

    // Assert that at least one search criteria appears valid

    ASSERT(clusFirst != UNKNOWN_CLUSTER? TRUE : (int)psid);

    EnterCriticalSection(&pvol->v_csStms);

    // If the caller wants to create a private stream, then skip the search
    //創(chuàng)建private的stream
    if ((dwFlags & (OPENSTREAM_CREATE|OPENSTREAM_PRIVATE)) != (OPENSTREAM_CREATE|OPENSTREAM_PRIVATE)) {

        for (pstm = pvol->v_dlOpenStreams.pstmNext; pstm != (PDSTREAM)&pvol->v_dlOpenStreams; pstm = pstm->s_dlOpenStreams.pstmNext) {

            if (!(pstm->s_flags & STF_PRIVATE) != !(dwFlags & OPENSTREAM_PRIVATE))
                continue;

            if (clusFirst != UNKNOWN_CLUSTER &&
                    pstm->s_clusFirst == clusFirst ||
                clusFirst == UNKNOWN_CLUSTER &&
                    pstm->s_sid.sid_clusDir == psid->sid_clusDir && pstm->s_sid.sid_ordDir == psid->sid_ordDir) {

                ASSERT(pstm->s_refs != 0);
                goto init;
            }
        }
    }

    // The requested stream is not open.  Bail if the volume is unmounted and
    // has not yet been remounted or recycled, or if the volume is fine and we
    // simply cannot allocate memory for a new stream.

    if (!(dwFlags & OPENSTREAM_CREATE) ||
        (pvol->v_flags & (VOLF_UNMOUNTED | VOLF_REMOUNTED | VOLF_RECYCLED)) == VOLF_UNMOUNTED ||
        !(pstm = HeapAlloc(hHeap, HEAP_ZERO_MEMORY, sizeof(DSTREAM)))) {

        LeaveCriticalSection(&pvol->v_csStms);
        return NULL;
    }
    DEBUGALLOC(sizeof(DSTREAM));

    // Initialize file lock state
    pFileLockState = &pstm->s_filelockstate;
    FSDMGR_OpenFileLockState(pFileLockState);
    // 對(duì)該stream的臨界區(qū)變量進(jìn)行初始化
    InitializeCriticalSection(&pstm->s_cs);
    DEBUGALLOC(DEBUGALLOC_CS);
    // 設(shè)置該stream的其它屬性
    pstm->s_pvol = pvol;
    pstm->s_flags = STF_VOLUME;

    pstm->s_clusFirst = clusFirst;
    if (psid)
        pstm->s_sid = *psid;

    pstm->s_blkDir = INVALID_BLOCK;
    // 初始化pstm->s_runList的所有單元，并對(duì)run的第一個(gè)slot開始簇設(shè)置為clusFirst
    InitStreamRunList (&pstm->s_runList, pvol, clusFirst);

    // If the caller wanted a PRIVATE root stream, then we have to clone
    // the appropriate fields from the volume's root stream.

    if (dwFlags & OPENSTREAM_PRIVATE) {
        ASSERT(clusFirst);
        pstm->s_flags |= STF_PRIVATE;
        if (clusFirst == ROOT_PSEUDO_CLUSTER) {
            pstm->s_runList = pvol->v_pstmRoot->s_runList;
            pstm->s_size = pvol->v_pstmRoot->s_size;
        }
    }
    //使pstm->s_dlOpenHandles得前向和后向都指向其本身
    InitList((PDLINK)&pstm->s_dlOpenHandles);
	
    AddItem((PDLINK)&pvol->v_dlOpenStreams, (PDLINK)&pstm->s_dlOpenStreams);

    // Common code for both cases (old stream, new stream).  An old
    // stream might have been created with minimal information by a thread
    // for its own minimal purposes, but if another thread requests the same
    // stream and provides more detailed information, we need to record/update
    // that information, so that the stream will satisfy both threads'
    // purposes.

  init:
    pstm->s_refs++;

#ifdef TFAT
    // TFAT, add a ref to the parent stream only if it was not added before
    if(pvol->v_fTfat && pstmParent)
    {
        if(pstm->s_pstmParent){
            ASSERT(pstm->s_pstmParent == pstmParent);
        }else{
            pstm->s_pstmParent = pstmParent;
            pstmParent->s_refs++;
        }
    }
#endif

    LeaveCriticalSection(&pvol->v_csStms);
    EnterCriticalSection(&pstm->s_cs);

    if (!pstm->s_clusFirst || pstm->s_clusFirst == UNKNOWN_CLUSTER)
        pstm->s_clusFirst = clusFirst;

    if (psid) {
        if (!pstm->s_sid.sid_clusDir || pstm->s_sid.sid_clusDir == UNKNOWN_CLUSTER) {
            pstm->s_sid = *psid;
        }
    }

    if (pdi && (!(pstm->s_flags & STF_INIT) || (dwFlags & OPENSTREAM_REFRESH))) {

        // Whenever pdi is provided, pstmParent must be provided too.

        ASSERT(pstmParent);

        // We save the OEM name in the DIRENTRY for validation during handle
        // regeneration.

        memcpy(pstm->s_achOEM, pdi->di_pde->de_name, sizeof(pdi->di_pde->de_name));

        // Mask off any invalid attributes
        pstm->s_attr = pdi->di_pde->de_attr & ~ATTR_INVALID;

        pstm->s_size = (pdi->di_pde->de_attr & ATTR_DIR_MASK) == ATTR_DIRECTORY? MAX_DIRSIZE : pdi->di_pde->de_size;

        pstm->s_sidParent = pstmParent->s_sid;
        pstm->s_cwPath = pdi->di_cwName + pstmParent->s_cwPath + 1;

#ifdef TFAT
        // Compensate for the TFAT hidden directory so it doesn't count against MAX_PATH
        if (pvol->v_fTfat && !(pvol->v_flags & VOLF_32BIT_FAT) && !(pvol->v_flFATFS & FATFS_DISABLE_TFAT_REDIR) &&
            !pstm->s_sidParent.sid_ordDir && !pstm->s_sidParent.sid_clusDir)
        {
            pstm->s_cwPath = 0;
        }
#endif

        // We should never need to query or update a DIRECTORY stream's
        // DIRENTRY however (or the date/time values inside it).

        if (!(pstm->s_attr & ATTR_DIRECTORY)) {

            pstm->s_flags &= ~STF_VOLUME;

            // As an optimization, remember the physical block and offset
            // within that block of the stream's DIRENTRY.  This will save
            // us from having to perform a OpenStream/FindNext combination
            // in CommitStream whenever we need to update a stream's DIRENTRY.

            // For that information to be available and valid, however, all
            // callers must have a "lock" on the parent stream, and the stream
            // in turn must have a "current buffer".

            ASSERT(OWNCRITICALSECTION(&pstmParent->s_cs));
            ASSERT(pstmParent->s_pbufCur);

            if (pstmParent->s_pbufCur) {
                pstm->s_blkDir = pstmParent->s_pbufCur->b_blk;
                pstm->s_offDir = (PBYTE)pdi->di_pde - pstmParent->s_pbufCur->b_pdata;
            }

            // DOSTimeToFileTime can fail because it doesn't range-check any of
            // the date/time values in the directory entry;  it just pulls them apart
            // and calls SystemTimeToFileTime, which won't initialize the FILETIME
            // structure if there's an error.  Fortunately, all the FILETIMEs have been
            // zero-initialized, because that's what the Win32 API dictates when a time
            // is unknown/not supported.

            DOSTimeToFileTime(pdi->di_pde->de_createdDate,
                              pdi->di_pde->de_createdTime,
                              pdi->di_pde->de_createdTimeMsec, &pstm->s_ftCreate);

            DOSTimeToFileTime(pdi->di_pde->de_date, pdi->di_pde->de_time, 0, &pstm->s_ftWrite);

            DOSTimeToFileTime(pdi->di_pde->de_lastAccessDate, 0, 0, &pstm->s_ftAccess);
        }

        pstm->s_flags |= STF_INIT;

    }

#ifdef DEBUG
    else {
        if (clusFirst == FAT_PSEUDO_CLUSTER)
            memcpy(pstm->s_achOEM, "<FAT>", 5);
        else if (clusFirst == ROOT_PSEUDO_CLUSTER)
            memcpy(pstm->s_achOEM, "<ROOT>", 6);
    }
#endif

    if (pvol->v_flFATFS & FATFS_FORCE_WRITETHROUGH) 
        pstm->s_flags |= STF_WRITETHRU;

    if (pvol->v_flFATFS & FATFS_TRANS_DATA) 
        pstm->s_flags |= STF_TRANSDATA;

    DEBUGMSGW(ZONE_STREAMS,(DBGTEXTW("FATFS!OpenStream %s stream 0x%08x for '%.11hs' (%d)\r\n"), pstm->s_refs > 1? TEXTW("opened") : TEXTW("created"), pstm, pstm->s_achOEM, pstm->s_refs));
    return pstm;
}

DWORD CloseStream(PDSTREAM pstm)
{
    DWORD dwError = ERROR_SUCCESS;
    PFILELOCKSTATE pFileLockState;
    PEMPTYLOCKCONTAINER pfnEmptyLockContainer;

    if (pstm) {

        PVOLUME pvol = pstm->s_pvol;

        ASSERT(OWNCRITICALSECTION(&pstm->s_cs));

        // When there is no lazy-writer, CloseStream may be the last opportunity we
        // have to visit buffers for this stream, so we need to call CommitStream(TRUE),
        // lest any buffers languish dirty indefinitely -- which would in turn increase
        // the chances of the media appearing inconsistent if it was removed unexpectedly.
        // Of course, we warn the user to put the media back in when that happens, but
        // it's best to prevent such warnings in the first place.
        //
        // When there IS a lazy-writer, we can let it take care of buffers for path-based
        // and volume-based streams, and invoke CommitStream(TRUE) only for handle-based streams.
        //
        // This logic is somewhat arbitrary -- we could always call CommitStream(FALSE) -- but
        // since files are often closed as a result of some explicit user action, and since such
        // actions often precede unexpected media removal, I'm not exactly being paranoid for
        // no reason here.... -JTP

        dwError = CommitStream(pstm, TRUE);

        ASSERT(!(pstm->s_flags & STF_BUFCURHELD) && pstm->s_pbufCur == NULL);

        LeaveCriticalSection(&pstm->s_cs);
        EnterCriticalSection(&pvol->v_csStms);
        // 該stream被引用的次數(shù)為1
        if (--pstm->s_refs == 0) {

#ifdef TFAT
            // TFAT, lower the refcount on the parent stream
            if(pvol->v_fTfat && pstm->s_pstmParent)
            {
                ASSERT(pstm->s_pstmParent->s_refs);
                if(1 == pstm->s_pstmParent->s_refs){
                    EnterCriticalSection(&pstm->s_pstmParent->s_cs);
                    CloseStream(pstm->s_pstmParent);
                } else{
                    --pstm->s_pstmParent->s_refs;
                }
            }
#endif

            // Deinitialize file lock state
            pFileLockState = &pstm->s_filelockstate;
            pfnEmptyLockContainer = FSDMGR_EmptyLockContainer;
            FSDMGR_CloseFileLockState(pFileLockState, pfnEmptyLockContainer);

            DEBUGMSG(ZONE_STREAMS,(DBGTEXT("FATFS!CloseStream destroying stream 0x%08x for '%.11hs'\r\n"), pstm, pstm->s_achOEM));
            // 從鏈表	pstm->s_dlOpenStreams上刪除一個(gè)stream節(jié)點(diǎn)
            RemoveItem((PDLINK)&pstm->s_dlOpenStreams);

            PathCacheStreamInvalidate (pvol, pstm);
            InvalidateSteamBuffer (pstm);

            DEBUGFREE(DEBUGALLOC_CS);
            DeleteCriticalSection(&pstm->s_cs);
            DEBUGFREE(sizeof(DSTREAM));
            VERIFYTRUE(HeapFree(hHeap, 0, pstm));

            
        } else {
            DEBUGMSG(ZONE_STREAMS,(DBGTEXT("FATFS!CloseStream stream 0x%08x for '%.11hs' has %d refs\r\n"), pstm, pstm->s_achOEM, pstm->s_refs));
        }

        LeaveCriticalSection(&pvol->v_csStms);
    }
    return dwError;
}


/*  CommitStream - flush buffers (and DIRENTRY) associated with this stream
 *
 *  ENTRY
 *      pstm - pointer to DSTREAM
 *      fAll - TRUE to commit all stream buffers, FALSE to just update DIRENTRY
 *
 *  EXIT
 *      ERROR_SUCCESS (0) if successful, non-zero if not
 *
 *  NOTES
 *      As an optimization, OpenStream remembers the physical block and
 *      within that block of the stream's DIRENTRY.  This will save
 *      us from having to perform a OpenStream/FindNext combination
 *      in CommitStream every time we need to update a stream's DIRENTRY.
 *
 *      As an added optimization, OpenStream also records the parent's OID
 *      if a parent stream was specified when the stream was created.  Thus,
 *      CommitStream has all the information it needs to post a CEOID_CHANGED
 *      message if the stream changed, again without having to open the
 *      parent stream.
 */

DWORD CommitStream(PDSTREAM pstm, BOOL fAll)
{
    DWORD dwError = ERROR_SUCCESS;

    ASSERT(OWNCRITICALSECTION(&pstm->s_cs));

    // NOTE: CommitStream refuses to update an unmounted stream because
    // the volume the stream was associated with may have been unmounted and
    // RECYCLED, in which case this stream is dead and its directory entry
    // can never be safely updated.  The stream will eventually go away when
    // all the apps with handles to the stream close their handles.

    if (!(pstm->s_flags & STF_UNMOUNTED)) {

        // Commit all dirty buffers associated with this stream.  There
        // is no return value from this function.  Any held stream buffer will
        // be released as well.

        if (!fAll)
            dwError = ReleaseStreamBuffer(pstm, FALSE);
        else
            dwError = CommitAndReleaseStreamBuffers(pstm);

        // The rest of this is for non-FAT, non-root, non-directory
        // streams only (ie, streams with DIRENTRY's that should be updated).

        if (!(pstm->s_flags & STF_VOLUME)) {

            SYSTEMTIME stLocal;

            GetLocalTime(&stLocal);

            // A stream gets a new access time if it's a new day, unless
            // STF_ACCESS_TIME is set, in which case someone has already set a
            // specific access time.

            
            if ((pstm->s_pvol->v_flags & VOLF_UPDATE_ACCESS) && !(pstm->s_flags & STF_ACCESS_TIME)) {

                SYSTEMTIME stTmp;
                FILETIME ftTmp1, ftTmp2;

                stTmp = stLocal;
                stTmp.wDayOfWeek = stTmp.wHour = stTmp.wMinute = stTmp.wSecond = stTmp.wMilliseconds = 0;

                // Now that I've truncated the local system time to midnight,