// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

import "unknwn.idl";
import "objidl.idl";

// Forward declarations
interface ICLRPrivBinder;
interface ICLRPrivAssembly;

/**************************************************************************************
 ** This IDL file defines the assembly binding host interfaces. Some things to keep
 ** in mind:
 **    - Equality is determined by pointer equality: two interface instances
 **      should be considered equal if and only if their pointer values are equal.
 **    - All operations are idempotent: when a method is called more than once with
 **      the same input values, it is required to return identical results. The only
 **      possible exceptions center around transient errors such as E_OUTOFMEMORY.
 **************************************************************************************/

/**************************************************************************************
 ** ICLRPrivBinder - Use to bind to an assembly by name or by metadata reference.
 **************************************************************************************/
[
    uuid(2601F621-E462-404C-B299-3E1DE72F8542),
    version(1.0),
    local
]
interface ICLRPrivBinder : IUnknown
{
    /**********************************************************************************
     ** BindAssemblyByName -- Binds an assembly by name.
     **     NOTE: This method is required to be idempotent. See general comment above.
     **
     ** pAssemblyFullName - name of the assembly for which a bind is being requested.
     ** ppAssembly - upon success, receives the bound assembly.
     **********************************************************************************/
    HRESULT BindAssemblyByName(
        [in] struct AssemblyNameData* pAssemblyNameData,
        [out, retval] ICLRPrivAssembly ** ppAssembly);

    /**********************************************************************************
     ** GetBinderID
     **  pBinderId, pointer to binder id. The binder id has the following properties
     **        It is a pointer that does not change over the lifetime of a binder object
     **        It points at an object in memory that will remain allocated for the lifetime of the binder.
     **        This value should be the same for a set of binder objects that represent the same binder behavior.
     **********************************************************************************/
    HRESULT GetBinderID(
        [out, retval] UINT_PTR *pBinderId);

    /**********************************************************************************
     ** GetLoaderAllocator
     ** Get LoaderAllocator for binders that contain it. For other binders, return
     ** E_FAIL
     **
     **  pLoaderAllocator - when successful, constains the returned LoaderAllocator
     **********************************************************************************/
    HRESULT GetLoaderAllocator(
        [out, retval] LPVOID * pLoaderAllocator);
};

/**************************************************************************************
 ** ASSEMBLY_IMAGE_TYPES - The set of assembly image formats.
 **************************************************************************************/
enum ASSEMBLY_IMAGE_TYPES
{
    // IL image format
    ASSEMBLY_IMAGE_TYPE_IL                      = 0x0001,
    // Native image (NGEN) format
    ASSEMBLY_IMAGE_TYPE_NATIVE                  = 0x0002,
    // Binder's preferred image type
    ASSEMBLY_IMAGE_TYPE_DEFAULT                 = 0x0003,
    // Only supported on CoreCLR
    ASSEMBLY_IMAGE_TYPE_ASSEMBLY                = 0x0004,
};

/**************************************************************************************
 ** ICLRPrivAssembly - Represents an assembly bind result. Extends ICLRPrivBinder, which
 ** implicitly tracks the parent binder, and enables simple assembly-relative binds.
 **************************************************************************************/
[
    uuid(2601F621-E462-404C-B299-3E1DE72F8543),
    version(1.0),
    local
]
interface ICLRPrivAssembly : ICLRPrivBinder
{
    /**********************************************************************************
     ** GetAvailableImageTypes - Use to retrieve the set of images available for an
     ** assembly.
     **     NOTE: This method is required to be idempotent. See general comment above.
     **
     ** pdwImageTypes - set to values from ASSEMBLY_IMAGE_TYPES to indicate
     **     which image formats are available for the assembly.
     **********************************************************************************/
    HRESULT GetAvailableImageTypes(
        [out, retval] LPDWORD pdwImageTypes);
};