LocationGlobber.cs

/********************************************************************++
Copyright (c) Microsoft Corporation.  All rights reserved.
--********************************************************************/

using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Management.Automation.Provider;
using System.Text;
using Dbg = System.Management.Automation;

namespace System.Management.Automation
{
    /// <summary>
    /// Implements the interfaces used by navigation commands to work with
    /// the virtual drive system.
    /// </summary>
    internal sealed class LocationGlobber
    {
        #region Trace object

        /// <summary>
        /// An instance of the PSTraceSource class used for trace output
        /// using "LocationGlobber" as the category.
        /// </summary>
        [Dbg.TraceSourceAttribute(
             "LocationGlobber",
             "The location globber converts PowerShell paths with glob characters to zero or more paths.")]
        private static Dbg.PSTraceSource s_tracer =
            Dbg.PSTraceSource.GetTracer("LocationGlobber",
             "The location globber converts PowerShell paths with glob characters to zero or more paths.");

        /// <summary>
        /// User level tracing for path resolution.
        /// </summary>
        [Dbg.TraceSourceAttribute(
             "PathResolution",
             "Traces the path resolution algorithm.")]
        private static Dbg.PSTraceSource s_pathResolutionTracer =
            Dbg.PSTraceSource.GetTracer(
                "PathResolution",
                "Traces the path resolution algorithm.",
                false);

        #endregion Trace object

        #region Constructor

        /// <summary>
        /// Constructs an instance of the LocationGlobber from the current SessionState
        /// </summary>
        ///
        /// <param name="sessionState">
        /// The instance of session state on which this location globber acts.
        /// </param>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="sessionState" /> is null.
        /// </exception>
        ///
        internal LocationGlobber(SessionState sessionState)
        {
            if (sessionState == null)
            {
                throw PSTraceSource.NewArgumentNullException("sessionState");
            }

            _sessionState = sessionState;
        } // LocationGlobber(SessionState)

        #endregion Constructor

        #region Public methods

        #region PowerShell paths from PowerShell path globbing
        /// <summary>
        /// Converts a PowerShell path containing glob characters to PowerShell paths that match
        /// the glob string.
        /// </summary>
        ///
        /// <param name="path">
        /// A PowerShell path containing glob characters.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// The provider instance used to resolve the path.
        /// </param>
        ///
        /// <returns>
        /// The PowerShell paths that match the glob string.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/> is null.
        /// </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If <paramref name="path"/> is a provider-qualified path
        /// and the specified provider does not exist.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider throws an exception when its MakePath gets
        /// called.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the provider does not support multiple items.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the home location for the provider is not set and
        /// <paramref name="path"/> starts with a "~".
        /// </exception>
        ///
        /// <exception cref="ItemNotFoundException">
        /// If <paramref name="path"/> does not contain glob characters and
        /// could not be found.
        /// </exception>
        ///
        internal Collection<PathInfo> GetGlobbedMonadPathsFromMonadPath(
            string path,
            bool allowNonexistingPaths,
            out CmdletProvider providerInstance)
        {
            CmdletProviderContext context =
                new CmdletProviderContext(_sessionState.Internal.ExecutionContext);

            return GetGlobbedMonadPathsFromMonadPath(path, allowNonexistingPaths, context, out providerInstance);
        } // GetGlobbedMonadPathsFromMonadPath

        /// <summary>
        /// Converts a PowerShell path containing glob characters to PowerShell paths that match
        /// the glob string.
        /// </summary>
        ///
        /// <param name="path">
        /// A PowerShell path containing glob characters.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="context">
        /// The context under which the command is running.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// The instance of the provider used to resolve the path.
        /// </param>
        ///
        /// <returns>
        /// The PowerShell paths that match the glob string.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/> or <paramref name="context"/> is null.
        /// </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If <paramref name="path"/> is a provider-qualified path
        /// and the specified provider does not exist.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider throws an exception when its MakePath gets
        /// called.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the provider does not support multiple items.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the home location for the provider is not set and
        /// <paramref name="path"/> starts with a "~".
        /// </exception>
        ///
        /// <exception cref="ItemNotFoundException">
        /// If <paramref name="path"/> does not contain glob characters and
        /// could not be found.
        /// </exception>
        ///
        /// <exception cref="PipelineStoppedException">
        /// If <paramref name="context"/> has been signaled for
        /// StopProcessing.
        /// </exception>
        ///
        internal Collection<PathInfo> GetGlobbedMonadPathsFromMonadPath(
            string path,
            bool allowNonexistingPaths,
            CmdletProviderContext context,
            out CmdletProvider providerInstance)
        {
            providerInstance = null;
            if (path == null)
            {
                throw PSTraceSource.NewArgumentNullException("path");
            }

            if (context == null)
            {
                throw PSTraceSource.NewArgumentNullException("context");
            }

            Collection<PathInfo> result;

            using (s_pathResolutionTracer.TraceScope("Resolving MSH path \"{0}\" to MSH path", path))
            {
                TraceFilters(context);

                // First check to see if the path starts with a ~ (home)

                if (IsHomePath(path))
                {
                    using (s_pathResolutionTracer.TraceScope("Resolving HOME relative path."))
                    {
                        path = GetHomeRelativePath(path);
                    }
                }

                // Now determine how to parse the path

                bool isProviderDirectPath = IsProviderDirectPath(path);
                bool isProviderQualifiedPath = IsProviderQualifiedPath(path);
                if (isProviderDirectPath || isProviderQualifiedPath)
                {
                    result =
                        ResolvePSPathFromProviderPath(
                            path,
                            context,
                            allowNonexistingPaths,
                            isProviderDirectPath,
                            isProviderQualifiedPath,
                            out providerInstance);
                }
                else
                {
                    result =
                        ResolveDriveQualifiedPath(
                            path,
                            context,
                            allowNonexistingPaths,
                            out providerInstance);
                }

                if (!allowNonexistingPaths &&
                    result.Count < 1 &&
                    !WildcardPattern.ContainsWildcardCharacters(path) &&
                    (context.Include == null || context.Include.Count == 0) &&
                    (context.Exclude == null || context.Exclude.Count == 0))
                {
                    // Since we are not globbing, throw an exception since
                    // the path doesn't exist

                    ItemNotFoundException pathNotFound =
                        new ItemNotFoundException(
                            path,
                            "PathNotFound",
                            SessionStateStrings.PathNotFound);

                    s_pathResolutionTracer.TraceError("Item does not exist: {0}", path);

                    throw pathNotFound;
                }
            }
            return result;
        } // GetGlobbedMonadPathsFromMonadPath

        private Collection<string> ResolveProviderPathFromProviderPath(
            string providerPath,
            string providerId,
            bool allowNonexistingPaths,
            CmdletProviderContext context,
            out CmdletProvider providerInstance
            )
        {
            // Check the provider capabilities before globbing
            providerInstance = _sessionState.Internal.GetProviderInstance(providerId);
            ContainerCmdletProvider containerCmdletProvider = providerInstance as ContainerCmdletProvider;
            ItemCmdletProvider itemProvider = providerInstance as ItemCmdletProvider;

            Collection<string> stringResult = new Collection<string>();

            if (!context.SuppressWildcardExpansion)
            {
                // See if the provider will expand the wildcard
                if (CmdletProviderManagementIntrinsics.CheckProviderCapabilities(
                        ProviderCapabilities.ExpandWildcards,
                        providerInstance.ProviderInfo))
                {
                    s_pathResolutionTracer.WriteLine("Wildcard matching is being performed by the provider.");

                    // Only do the expansion if the path actually contains wildcard
                    // characters.
                    if ((itemProvider != null) &&
                        (WildcardPattern.ContainsWildcardCharacters(providerPath)))
                    {
                        stringResult = new Collection<string>(itemProvider.ExpandPath(providerPath, context));
                    }
                    else
                    {
                        stringResult.Add(providerPath);
                    }
                }
                else
                {
                    s_pathResolutionTracer.WriteLine("Wildcard matching is being performed by the engine.");

                    if (containerCmdletProvider != null)
                    {
                        // Since it is really a provider-internal path, use provider-to-provider globbing
                        // and then add back on the provider ID.

                        stringResult =
                            GetGlobbedProviderPathsFromProviderPath(
                                providerPath,
                                allowNonexistingPaths,
                                containerCmdletProvider,
                                context);
                    }
                    else
                    {
                        // For simple CmdletProvider instances, we can't resolve the paths any
                        // further, so just return the providerPath
                        stringResult.Add(providerPath);
                    }
                }
            }
            // They are suppressing wildcard expansion
            else
            {
                if (itemProvider != null)
                {
                    if (allowNonexistingPaths || itemProvider.ItemExists(providerPath, context))
                    {
                        stringResult.Add(providerPath);
                    }
                }
                else
                {
                    stringResult.Add(providerPath);
                }
            }

            // Make sure this resolved to something
            if ((!allowNonexistingPaths) &&
                stringResult.Count < 1 &&
                !WildcardPattern.ContainsWildcardCharacters(providerPath) &&
                (context.Include == null || context.Include.Count == 0) &&
                (context.Exclude == null || context.Exclude.Count == 0))
            {
                ItemNotFoundException pathNotFound =
                    new ItemNotFoundException(
                        providerPath,
                        "PathNotFound",
                        SessionStateStrings.PathNotFound);

                s_pathResolutionTracer.TraceError("Item does not exist: {0}", providerPath);
                throw pathNotFound;
            }

            return stringResult;
        }

        private Collection<PathInfo> ResolvePSPathFromProviderPath(
            string path,
            CmdletProviderContext context,
            bool allowNonexistingPaths,
            bool isProviderDirectPath,
            bool isProviderQualifiedPath,
            out CmdletProvider providerInstance)
        {
            Collection<PathInfo> result = new Collection<PathInfo>();

            providerInstance = null;
            string providerId = null;
            PSDriveInfo drive = null;

            // The path is a provide direct path so use the current
            // provider and don't modify the path.

            string providerPath = null;

            if (isProviderDirectPath)
            {
                s_pathResolutionTracer.WriteLine("Path is PROVIDER-DIRECT");
                providerPath = path;
                providerId = _sessionState.Path.CurrentLocation.Provider.Name;
            }
            else if (isProviderQualifiedPath)
            {
                s_pathResolutionTracer.WriteLine("Path is PROVIDER-QUALIFIED");
                providerPath = ParseProviderPath(path, out providerId);
            }

            s_pathResolutionTracer.WriteLine("PROVIDER-INTERNAL path: {0}", providerPath);
            s_pathResolutionTracer.WriteLine("Provider: {0}", providerId);

            Collection<string> stringResult = ResolveProviderPathFromProviderPath(
                providerPath,
                providerId,
                allowNonexistingPaths,
                context,
                out providerInstance
                );

            // Get the hidden drive for the provider
            drive = providerInstance.ProviderInfo.HiddenDrive;

            // Now fix the paths
            foreach (string globbedPath in stringResult)
            {
                string escapedPath = globbedPath;

                // Making sure to obey the StopProcessing.
                if (context.Stopping)
                {
                    throw new PipelineStoppedException();
                }

                string constructedProviderPath = null;

                if (IsProviderDirectPath(escapedPath))
                {
                    constructedProviderPath = escapedPath;
                }
                else
                {
                    constructedProviderPath =
                        String.Format(
                            System.Globalization.CultureInfo.InvariantCulture,
                            "{0}::{1}",
                            providerId,
                            escapedPath);
                }

                result.Add(new PathInfo(drive, providerInstance.ProviderInfo, constructedProviderPath, _sessionState));
                s_pathResolutionTracer.WriteLine("RESOLVED PATH: {0}", constructedProviderPath);
            }

            return result;
        }

        private Collection<PathInfo> ResolveDriveQualifiedPath(
            string path,
            CmdletProviderContext context,
            bool allowNonexistingPaths,
            out CmdletProvider providerInstance)
        {
            providerInstance = null;
            PSDriveInfo drive = null;

            Collection<PathInfo> result = new Collection<PathInfo>();

            s_pathResolutionTracer.WriteLine("Path is DRIVE-QUALIFIED");

            string relativePath = GetDriveRootRelativePathFromPSPath(path, context, true, out drive, out providerInstance);

            Dbg.Diagnostics.Assert(
                drive != null,
                "GetDriveRootRelativePathFromPSPath should always return a valid drive");

            Dbg.Diagnostics.Assert(
                relativePath != null,
                "There should always be a way to generate a provider path for a " +
                "given path");

            s_pathResolutionTracer.WriteLine("DRIVE-RELATIVE path: {0}", relativePath);
            s_pathResolutionTracer.WriteLine("Drive: {0}", drive.Name);
            s_pathResolutionTracer.WriteLine("Provider: {0}", drive.Provider);

            // Associate the drive with the context

            context.Drive = drive;
            providerInstance = _sessionState.Internal.GetContainerProviderInstance(drive.Provider);
            ContainerCmdletProvider containerCmdletProvider = providerInstance as ContainerCmdletProvider;
            ItemCmdletProvider itemProvider = providerInstance as ItemCmdletProvider;

            ProviderInfo provider = providerInstance.ProviderInfo;

            string userPath = null;
            string itemPath = null;

            if (drive.Hidden)
            {
                userPath = GetProviderQualifiedPath(relativePath, provider);
                itemPath = relativePath;
            }
            else
            {
                userPath = GetDriveQualifiedPath(relativePath, drive);
                itemPath = GetProviderPath(path, context);
            }
            s_pathResolutionTracer.WriteLine("PROVIDER path: {0}", itemPath);

            Collection<string> stringResult = new Collection<string>();

            if (!context.SuppressWildcardExpansion)
            {
                // See if the provider will expand the wildcard
                if (CmdletProviderManagementIntrinsics.CheckProviderCapabilities(
                        ProviderCapabilities.ExpandWildcards,
                        provider))
                {
                    s_pathResolutionTracer.WriteLine("Wildcard matching is being performed by the provider.");

                    // Only do the expansion if the path actually contains wildcard
                    // characters.
                    if ((itemProvider != null) &&
                        (WildcardPattern.ContainsWildcardCharacters(relativePath)))
                    {
                        foreach (string pathResult in itemProvider.ExpandPath(itemPath, context))
                        {
                            stringResult.Add(
                                GetDriveRootRelativePathFromProviderPath(pathResult, drive, context));
                        }
                    }
                    else
                    {
                        stringResult.Add(GetDriveRootRelativePathFromProviderPath(itemPath, drive, context));
                    }
                }
                else
                {
                    s_pathResolutionTracer.WriteLine("Wildcard matching is being performed by the engine.");

                    // Now perform the globbing
                    stringResult =
                        ExpandMshGlobPath(
                            relativePath,
                            allowNonexistingPaths,
                            drive,
                            containerCmdletProvider,
                            context);
                }
            }
            // They are suppressing wildcard expansion
            else
            {
                if (itemProvider != null)
                {
                    if (allowNonexistingPaths || itemProvider.ItemExists(itemPath, context))
                    {
                        stringResult.Add(userPath);
                    }
                }
                else
                {
                    stringResult.Add(userPath);
                }
            }

            // Make sure this resolved to something
            if ((!allowNonexistingPaths) &&
                stringResult.Count < 1 &&
                !WildcardPattern.ContainsWildcardCharacters(path) &&
                (context.Include == null || context.Include.Count == 0) &&
                (context.Exclude == null || context.Exclude.Count == 0))
            {
                ItemNotFoundException pathNotFound =
                    new ItemNotFoundException(
                        path,
                        "PathNotFound",
                        SessionStateStrings.PathNotFound);

                s_pathResolutionTracer.TraceError("Item does not exist: {0}", path);
                throw pathNotFound;
            }

            // Now fix the paths
            foreach (string expandedPath in stringResult)
            {
                // Make sure to obey StopProcessing
                if (context.Stopping)
                {
                    throw new PipelineStoppedException();
                }

                // Add the drive back into the path
                userPath = null;

                if (drive.Hidden)
                {
                    if (IsProviderDirectPath(expandedPath))
                    {
                        userPath = expandedPath;
                    }
                    else
                    {
                        userPath =
                            LocationGlobber.GetProviderQualifiedPath(
                                expandedPath,
                                provider);
                    }
                }
                else
                {
                    userPath =
                        LocationGlobber.GetDriveQualifiedPath(
                                expandedPath,
                                drive);
                }

                result.Add(new PathInfo(drive, provider, userPath, _sessionState));
                s_pathResolutionTracer.WriteLine("RESOLVED PATH: {0}", userPath);
            }

            return result;
        }

        #endregion PowerShell paths from PowerShell path globbing

        #region Provider paths from PowerShell path globbing

        /// <summary>
        /// Converts a PowerShell path containing glob characters to the provider
        /// specific paths matching the glob strings.
        /// </summary>
        ///
        /// <param name="path">
        /// A PowerShell path containing glob characters.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="provider">
        /// Returns the information of the provider that was used to do the globbing.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// The instance of the provider used to resolve the path.
        /// </param>
        ///
        /// <returns>
        /// An array of provider specific paths that matched the PowerShell glob path.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/> is null.
        /// </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If the path is a provider-qualified path for a provider that is
        /// not loaded into the system.
        /// </exception>
        ///
        /// <exception cref="DriveNotFoundException">
        /// If the <paramref name="path"/> refers to a drive that could not be found.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider used to build the path threw an exception.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider
        /// or ContainerCmdletProvider.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the <paramref name="path"/> starts with "~" and the home location is not set for
        /// the provider.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider associated with the <paramref name="path"/> threw an
        /// exception when its GetParentPath or MakePath was called while
        /// processing the <paramref name="path"/>.
        /// </exception>
        ///
        /// <exception cref="ItemNotFoundException">
        /// If <paramref name="path"/> does not contain glob characters and
        /// could not be found.
        /// </exception>
        ///
        /// <exception>
        /// Any exception can be thrown by the provider that is called to build
        /// the provider path.
        /// </exception>
        ///
        internal Collection<string> GetGlobbedProviderPathsFromMonadPath(
            string path,
            bool allowNonexistingPaths,
            out ProviderInfo provider,
            out CmdletProvider providerInstance)
        {
            providerInstance = null;
            if (path == null)
            {
                throw PSTraceSource.NewArgumentNullException("path");
            }

            CmdletProviderContext context =
                new CmdletProviderContext(_sessionState.Internal.ExecutionContext);

            return GetGlobbedProviderPathsFromMonadPath(path, allowNonexistingPaths, context, out provider, out providerInstance);
        } // GetGlobbedProviderPathsFromMonadPath

        /// <summary>
        /// Converts a PowerShell path containing glob characters to the provider
        /// specific paths matching the glob strings.
        /// </summary>
        ///
        /// <param name="path">
        /// A PowerShell path containing glob characters.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="context">
        /// The context under which the command is running.
        /// </param>
        ///
        /// <param name="provider">
        /// Returns the information of the provider that was used to do the globbing.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// The instance of the provider used to resolve the path.
        /// </param>
        ///
        /// <returns>
        /// An array of provider specific paths that matched the PowerShell glob path.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/> or <paramref name="context"/> is null.
        /// </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If the path is a provider-qualified path for a provider that is
        /// not loaded into the system.
        /// </exception>
        ///
        /// <exception cref="DriveNotFoundException">
        /// If the <paramref name="path"/> refers to a drive that could not be found.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider used to build the path threw an exception.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the provider that the <paramref name="path"/> represents is not a NavigationCmdletProvider
        /// or ContainerCmdletProvider.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the <paramref name="path"/> starts with "~" and the home location is not set for
        /// the provider.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider associated with the <paramref name="path"/> threw an
        /// exception when its GetParentPath or MakePath was called while
        /// processing the <paramref name="path"/>.
        /// </exception>
        ///
        /// <exception cref="ItemNotFoundException">
        /// If <paramref name="path"/> does not contain glob characters and
        /// could not be found.
        /// </exception>
        ///
        /// <exception>
        /// Any exception can be thrown by the provider that is called to build
        /// the provider path.
        /// </exception>
        ///
        internal Collection<string> GetGlobbedProviderPathsFromMonadPath(
            string path,
            bool allowNonexistingPaths,
            CmdletProviderContext context,
            out ProviderInfo provider,
            out CmdletProvider providerInstance)
        {
            if (path == null)
            {
                throw PSTraceSource.NewArgumentNullException("path");
            }

            if (context == null)
            {
                throw PSTraceSource.NewArgumentNullException("context");
            }

            using (s_pathResolutionTracer.TraceScope("Resolving MSH path \"{0}\" to PROVIDER-INTERNAL path", path))
            {
                TraceFilters(context);

                // Remove the drive from the context if this path is not associated with a drive
                if (IsProviderQualifiedPath(path))
                {
                    context.Drive = null;
                }

                PSDriveInfo drive = null;
                string providerPath = GetProviderPath(path, context, out provider, out drive);

                if (providerPath == null)
                {
                    providerInstance = null;
                    s_tracer.WriteLine("provider returned a null path so return an empty array");

                    s_pathResolutionTracer.WriteLine("Provider '{0}' returned null", provider);
                    return new Collection<string>();
                }

                if (drive != null)
                {
                    context.Drive = drive;
                }


                Collection<string> paths = new Collection<string>();

                foreach (PathInfo currentPath in
                    GetGlobbedMonadPathsFromMonadPath(
                        path,
                        allowNonexistingPaths,
                        context,
                        out providerInstance))
                {
                    paths.Add(currentPath.ProviderPath);
                }

                return paths;
            }
        } // GetGlobbedProviderPathsFromMonadPath

        #endregion Provider paths from Monad path globbing

        #region Provider paths from provider path globbing

        /// <summary>
        /// Given a provider specific path that contains glob characters, this method
        /// will perform the globbing using the specified provider and return the
        /// matching provider specific paths.
        /// </summary>
        ///
        /// <param name="path">
        /// The path containing the glob characters to resolve.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="providerId">
        /// The ID of the provider to use to do the resolution.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// The instance of the provider that was used to resolve the path.
        /// </param>
        ///
        /// <returns>
        /// An array of provider specific paths that match the glob path.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/> is null.
        /// </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If <paramref name="providerId"/> references a provider that does not exist.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the <paramref name="providerId"/> references a provider that is not
        /// a ContainerCmdletProvider.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider used to build the path threw an exception.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the <paramref name="path"/> starts with "~" and the home location is not set for
        /// the provider.
        /// </exception>
        ///
        /// <exception cref="ItemNotFoundException">
        /// If <paramref name="path"/> does not contain glob characters and
        /// could not be found.
        /// </exception>
        ///
        /// <exception>
        /// Any exception can be thrown by the provider that is called to build
        /// the provider path.
        /// </exception>
        ///
        internal Collection<string> GetGlobbedProviderPathsFromProviderPath(
            string path,
            bool allowNonexistingPaths,
            string providerId,
            out CmdletProvider providerInstance)
        {
            providerInstance = null;

            if (path == null)
            {
                throw PSTraceSource.NewArgumentNullException("path");
            }

            CmdletProviderContext context =
                new CmdletProviderContext(_sessionState.Internal.ExecutionContext);

            Collection<string> results =
                GetGlobbedProviderPathsFromProviderPath(
                    path,
                    allowNonexistingPaths,
                    providerId,
                    context,
                    out providerInstance);

            if (context.HasErrors())
            {
                // Throw the first error
                ErrorRecord errorRecord = context.GetAccumulatedErrorObjects()[0];

                if (errorRecord != null)
                {
                    throw errorRecord.Exception;
                }
            }
            return results;
        } // GetGlobbedProviderPathsFromProviderPath

        /// <summary>
        /// Given a provider specific path that contains glob characters, this method
        /// will perform the globbing using the specified provider and return the
        /// matching provider specific paths.
        /// </summary>
        ///
        /// <param name="path">
        /// The path containing the glob characters to resolve. The path must be in the
        /// form providerId::providerPath.
        /// </param>
        ///
        /// <param name="allowNonexistingPaths">
        /// If true, a ItemNotFoundException will not be thrown for non-existing
        /// paths. Instead an appropriate path will be returned as if it did exist.
        /// </param>
        ///
        /// <param name="providerId">
        /// The provider identifier for the provider to use to do the globbing.
        /// </param>
        ///
        /// <param name="context">
        /// The context under which the command is occurring.
        /// </param>
        ///
        /// <param name="providerInstance">
        /// An instance of the provider that was used to perform the globbing.
        /// </param>
        ///
        /// <returns>
        /// An array of provider specific paths that match the glob path.
        /// </returns>
        ///
        /// <exception cref="ArgumentNullException">
        /// If <paramref name="path"/>, <paramref name="providerId"/>, or
        /// <paramref name="context"/> is null.
        ///  </exception>
        ///
        /// <exception cref="ProviderNotFoundException">
        /// If <paramref name="providerId"/> references a provider that does not exist.
        /// </exception>
        ///
        /// <exception cref="NotSupportedException">
        /// If the <paramref name="providerId"/> references a provider that is not
        /// a ContainerCmdletProvider.
        /// </exception>
        ///
        /// <exception cref="ProviderInvocationException">
        /// If the provider used to build the path threw an exception.
        /// </exception>
        ///
        /// <exception cref="InvalidOperationException">
        /// If the <paramref name="path"/> starts with "~" and the home location is not set for
        /// the provider.
        /// </exception>
        ///
        /// <exception>
        /// Any exception can be thrown by the provider that is called to build
        /// the provider path.