/*
 * Copyright (c) Likewise Software.  All rights Reserved.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the license, or (at
 * your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser
 * General Public License for more details.  You should have received a copy
 * of the GNU Lesser General Public License along with this program.  If
 * not, see <http://www.gnu.org/licenses/>.
 *
 * LIKEWISE SOFTWARE MAKES THIS SOFTWARE AVAILABLE UNDER OTHER LICENSING
 * TERMS AS WELL.  IF YOU HAVE ENTERED INTO A SEPARATE LICENSE AGREEMENT
 * WITH LIKEWISE SOFTWARE, THEN YOU MAY ELECT TO USE THE SOFTWARE UNDER THE
 * TERMS OF THAT SOFTWARE LICENSE AGREEMENT INSTEAD OF THE TERMS OF THE GNU
 * LESSER GENERAL PUBLIC LICENSE, NOTWITHSTANDING THE ABOVE NOTICE.  IF YOU
 * HAVE QUESTIONS, OR WISH TO REQUEST A COPY OF THE ALTERNATE LICENSING
 * TERMS OFFERED BY LIKEWISE SOFTWARE, PLEASE CONTACT LIKEWISE SOFTWARE AT
 * license@likewisesoftware.com
 */

/*
 * Module Name:
 *
 *        fsd-guide.doxy
 *
 * Page Name:
 *
 *        fsd-snapshot.doxy
 *
 * Abstract:
 *
 *        Snapshot/Shadow Copy API documentation section of the file system driver
 *        guide
 *
 * Authors: Ki Anderson (kanderson@likewise.com)
 *
 */

/**
@page fsd-snapshot Snapshot/Shadow Copy

@section snapshot-summary Summary
The Likewise shadow copy API is an interface through which snapshots can be enumerated and requested.  The intention of the API is to shield the file system from the semantics of any particular request protocol (currently SMB and SMB2), and provide a unified method for accessing previous versions of files.

@section snapshot-details Shadow Copy API Details

@subsection indicating-support Indicating Support for Shadow Copy

A file system's support for shadow copy is indicated via an Extra Create Parameter (#ECP).  #IO_ECP_TYPE_UNDERSTAND_OPEN_SNAPSHOT is a boolean value, as defined in lwio/lwio-types.h.  Upon receipt of #IRP_TYPE_CREATE, the file system driver should search for #IO_ECP_TYPE_UNDERSTAND_OPEN_SNAPSHOT, and set its value to TRUE.  Systems which do not support shadow copy can safely ignore this ECP.

@subsection example-understand Example: Using IO_ECP_TYPE_UNDERSTAND_OPEN_SNAPSHOT

@code
PBOOLEAN pUnderstandSnapshot = NULL;
ULONG ulEcpSize = 0;
if (STATUS_SUCCESS == IoRtlEcpListFind(
			pIrp->Args.Create.EcpList,
			IO_ECP_TYPE_UNDERSTAND_OPEN_SNAPSHOT,
			OUT_PPVOID(&pUnderstandSnapshot),
			&ulEcpSize))
{
	*pUnderstandSnapshot = TRUE;
}
@endcode

@subsection listing-snapshots Listing Available Snapshots

#IO_FSCTL_QUERY_SNAPSHOTS indicates a request for a list of available snapshots for a given fileID.  The return buffer is an #IO_SNAPSHOT_LIST, structured as follows:

@code
IO_SNAPSHOT_LIST
{
    UINT32 NumberOfSnapshots;
    UINT32 NumberOfSnapshotsReturned;
    LONG64 SnapshotList[];
}
@endcode

- #NumberOfSnapshots:  The total number of snapshots available for the specified file or directory
- #NumberOfSnapshotsReturned:  The number of snapshots returned in SnapshotList[]
- #SnapshotList[]:  The list of available snapshots, specified as 64-bit signed integers corresponding to the FILETIME datatype specified in MS-DTYP section 2.3.1.  Note that while the resolution of FILETIME is 100 nanoseconds, shadow copies are specified with second resolution.  Times returned in SnapshotList[] should have 100 nanosecond resolution, but be rounded off to the nearest second.  Behavior for snapshotList[] entries that specify fractions of seconds is undefined.

The contents of SnapshotList[] and the value of NumberOfSnapshotsReturned are determined by the size of the output buffer provided with the FSCTL.  SnapshotList[] should be populated if and only if the output buffer is large enough to accommodate all of the available snapshots.  If the output buffer is not large enough, NumberOfSnapshotsReturned must be set to 0, and SnapshotList[] should be empty.  NumberOfSnapshots must be set in all cases.

@subsection snapshot-buff-all Example:  Buffer Accommodates All Snapshots
@code
IoSnapshotList.NumberOfSnapshots = <total available snapshots>
IoSnapshotList.NumberOfSnapshotsReturned = <total available snapshots>
IoSnapshotList.SnapshotList[0] = <first snapshot time>
IoSnapshotList.SnapshotList[1] = <second snapshot time>
...
@endcode

@subsection snapshot-buff-too-small Example:  Buffer Too Small for All Snapshots
@code
IoSnapshotList.NumberOfSnapshots = <total available snapshots>
IoSnapshotList.NumberOfSnapshotsReturned = 0
@endcode

@section opening-snapshot Opening a Specified Snapshot

Snapshots are specified by attaching #IO_ECP_TYPE_OPEN_SNAPSHOT (defined in lwio/io-types.h) to a file create operation:

@code
#define IO_ECP_TYPE_OPEN_SNAPSHOT "Likewise.IO.OpenSnapshot"
@endcode

The snapshot time in the ECP is a 64-bit signed integer indicating a #FILETIME, just like the times in SnapshotList[] above.
Read/write behavior (e.g. disallowing writes on opened snapshots) is the responsibility of the file system.

@subsection ecp-open Example:  Using  IO_ECP_TYPE_OPEN_SNAPSHOT

@code
PLONG64 pSnapshotTime = NULL;
ULONG ulEcpSize = 0;
if (STATUS_SUCCESS == IoRtlEcpListFind(
			pIrp->Args.Create.EcpList,
			IO_ECP_TYPE_OPEN_SNAPSHOT,
			OUT_PPVOID(&pSnapshotTime),
			&ulEcpSize))
{
	// Use *pSnapshotTime to open the appropriate snapshot
}
@endcode

@section snapshot-registry Registry Settings

The registry setting AlwaysParseSnapshotTime forces the server to parse paths for \@GMT tokens regardless of whether the client has set #SMB_FLAGS2_REPARSE_PATH (MS-SMB 2.2.3.1 ).  The purpose of this registry setting is to expose the previous version logic to applications that run on clients whose SMB client does not understand the #SMB_FLAGS2_REPARSE_PATH flag and does not set it (MS-SMB Appendix A, note <96>).
AlwaysParseSnapshotTime is available via lw-edit-reg under [HKEY_THIS_MACHINE\\Services\\lwio\\Parameters\\Drivers\\srv\\smb1].

@section snapshot-notes Notes

MS-SMB allows for enumeration of snapshots when the special token, \@GMT-*, is present in a #TRANS2_FIND_FIRST2 path (MS-SMB 3.3.5.9.2 ).  This method is not supported in Windows Server 2003 or Windows Server 2008 (MS-SMB Appendix A, note <110>), and is not supported by Likewise.

@section snapshot-references References

- MS-SMB  http://msdn.microsoft.com/en-us/library/cc246231.aspx
- MS-SMB2  http://msdn.microsoft.com/en-us/library/cc246482.aspx
- MS-CIFS  http://msdn.microsoft.com/en-us/library/ee442092.aspx
- MS-DTYP  http://msdn.microsoft.com/en-us/library/cc230273.aspx

**/
