using System;
using System.Runtime.InteropServices;
using EXCEPINFO = System.Runtime.InteropServices.ComTypes.EXCEPINFO;
namespace Vanara.PInvoke
{
public static partial class Ole32
{
/// Communicates detailed error information between a client and an object.
[ComImport, Guid("3127CA40-446E-11CE-8135-00AA004BB851"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
[PInvokeData("OAIdl.h")]
public interface IErrorLog
{
/// Logs an error (using an EXCEPINFO structure) in the error log for a named property.
///
/// A pointer to a string containing the name of the property involved with the error. This cannot be NULL.
///
///
/// A pointer to the caller-initialized EXCEPINFO structure that describes the error to log. This cannot be NULL.
///
void AddError([In, MarshalAs(UnmanagedType.LPWStr)] string pszPropName, in EXCEPINFO pExcepInfo);
}
/// Provides an object with a property bag in which the object can save its properties persistently.
///
/// To read a property in IPersistPropertyBag::Load, the object calls IPropertyBag::Read. When the object saves properties in
/// IPersistPropertyBag::Save, it calls IPropertyBag::Write. Each property is described with a name, whose value is stored in a
/// VARIANT. This information allows a client to save the property values as text, for example; which is the primary reason why a
/// client might choose to support IPersistPropertyBag.
///
[ComImport, Guid("55272A00-42CB-11CE-8135-00AA004BB851"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
[PInvokeData("OAIdl.h")]
public interface IPropertyBag
{
/// Tells the property bag to read the named property into a caller-initialized VARIANT.
/// The address of the name of the property to read. This cannot be NULL.
///
/// The address of the caller-initialized VARIANT that receives the property value on output. The function must set the type
/// field and the value field in the VARIANT before it returns. If the caller initialized the pVar->vt field on entry, the
/// property bag attempts to change its corresponding value to this type. If the caller sets pVar->vt to VT_EMPTY, the
/// property bag can use whatever type is convenient.
///
///
/// The address of the caller's error log in which the property bag stores any errors that occur during reads. This can be NULL;
/// in which case, the caller does not receive errors.
///
///
/// The Read method tells the property bag to read the property named in pszPropName to the caller-initialized VARIANT in pVar.
/// Errors are logged in the error log that is pointed to by pErrorLog. When pVar->vt specifies another object pointer
/// (VT_UNKNOWN), the property bag is responsible for creating and initializing the object described by pszPropName.
///
void Read([In, MarshalAs(UnmanagedType.LPWStr)] string pszPropName, [In, Out] ref object pVar, [In] IErrorLog pErrorLog);
/// Tells the property bag to save the named property in a caller-initialized VARIANT.
/// The address of a string containing the name of the property to write. This cannot be NULL.
///
/// The address of the caller-initialized VARIANT that holds the property value to save. The caller owns this VARIANT, and is
/// responsible for all of its allocations. That is, the property bag does not attempt to free data in the VARIANT.
///
///
/// The Write method tells the property bag to save the property named with pszPropName by using the type and value in the
/// caller-initialized VARIANT in pVar. In some cases, the caller might be telling the property bag to save another object, for
/// example, when pVar->vt is VT_UNKNOWN. In such cases, the property bag queries this object pointer for a persistence
/// interface, such as IPersistStream or IPersistPropertyBag, and has that object save its data as well. Usually this results in
/// the property bag having some byte array for this object, which can be saved as encoded text, such as hexadecimal string,
/// MIME, and so on. When the property bag is later used to reinitialize a control, the client that owns the property bag must
/// re-create the object when the caller asks for it, initializing that object with the previously saved bits.
///
/// This allows efficient persistence operations for Binary Large Object (BLOB) properties, such as a picture, where the owner of
/// the property bag tells the picture object (which is managed as a property in the control that is saved) to save to a specific
/// location. This avoids potential extra copy operations that might be involved with other property-based persistence mechanisms.
///
///
void Write([In, MarshalAs(UnmanagedType.LPWStr)] string pszPropName, in object pVar);
}
///
/// Describes the structure of a particular UDT. You can use IRecordInfo any time you need to access the description of UDTs
/// contained in type libraries. IRecordInfo can be reused as needed; there can be many instances of the UDT for a single IRecordInfo pointer.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nn-oaidl-irecordinfo
[PInvokeData("OAIdl.h")]
[ComImport, Guid("0000002F-0000-0000-C000-000000000046"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IRecordInfo
{
///
/// Initializes a new instance of a record.
///
///
/// An instance of a record.
///
///
/// The caller must allocate the memory of the record by its appropriate size using the GetSize method.
/// RecordInit sets all contents of the record to 0 and the record should hold no resources.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recordinit
void RecordInit(IntPtr pvNew);
///
/// Releases object references and other values of a record without deallocating the record.
///
///
/// The record to be cleared.
///
///
/// RecordClear releases memory blocks held by VT_PTR or VT_SAFEARRAY instance fields. The caller needs to free the
/// instance fields memory, RecordClear will do nothing if there are no resources held.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recordclear
void RecordClear(IntPtr pvExisting);
///
/// Copies an existing record into the passed in buffer.
///
///
/// The current record instance.
///
///
/// The destination where the record will be copied.
///
///
/// RecordCopy will release the resources in the destination first. The caller is responsible for allocating sufficient
/// memory in the destination by calling GetSize or RecordCreate. If RecordCopy fails to copy any of the fields then all
/// fields will be cleared, as though RecordClear had been called.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recordcopy
void RecordCopy(IntPtr pvExisting, IntPtr pvNew);
///
/// Gets the GUID of the record type.
///
///
/// The class GUID of the TypeInfo that describes the UDT.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getguid
Guid GetGuid();
///
///
/// Gets the name of the record type. This is useful if you want to print out the type of the record, because each UDT has it's
/// own IRecordInfo.
///
///
///
/// The name.
///
///
/// The caller must free the BSTR by calling SysFreeString.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getname
[return: MarshalAs(UnmanagedType.BStr)]
string GetName();
///
///
/// Gets the number of bytes of memory necessary to hold the record instance. This allows you to allocate memory for a record
/// instance rather than calling RecordCreate.
///
///
///
/// The size of a record instance, in bytes.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getsize
uint GetSize();
/// Retrieves the type information that describes a UDT or safearray of UDTs.
/// The type information.
/// AddRef is called on the pointer ppTypeInfo.
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-gettypeinfo
void GetTypeInfo([MarshalAs(UnmanagedType.CustomMarshaler, MarshalType = "System.Runtime.InteropServices.CustomMarshalers.TypeToTypeInfoMarshaler")] out Type ppTypeInfo);
///
/// Returns a pointer to the VARIANT containing the value of a given field name.
///
///
/// The instance of a record.
///
///
/// The field name.
///
///
/// The VARIANT that you want to hold the value of the field name, szFieldName. On return, places a copy of the field's value in
/// the variant.
///
///
///
/// The VARIANT that you pass in contains a copy of the field's value upon return. If you modify the VARIANT then the underlying
/// record field does not change.
///
/// The caller allocates memory of the VARIANT.
/// The method VariantClear is called for pvarField before copying.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getfield
[return: MarshalAs(UnmanagedType.Struct)]
object GetField(IntPtr pvData, [MarshalAs(UnmanagedType.LPWStr)] string szFieldName);
///
/// Returns a pointer to the value of a given field name without copying the value and allocating resources.
///
///
/// The instance of a record.
///
///
/// The name of the field.
///
///
/// The VARIANT that will contain the UDT upon return.
///
///
/// Receives the value of the field upon return.
///
///
///
/// Upon return, the VARIANT you pass contains a direct pointer to the record's field, ppvDataCArray. If you modify the VARIANT,
/// then the underlying record field will change.
///
///
/// The caller allocates memory of the VARIANT, but does not own the memory so cannot free pvarField. This method calls
/// VariantClear for pvarField before filling in the requested field.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getfieldnocopy
IntPtr GetFieldNoCopy(IntPtr pvData, [MarshalAs(UnmanagedType.LPWStr)] string szFieldName, [MarshalAs(UnmanagedType.Struct)] out object pvarField);
///
/// Puts a variant into a field.
///
///
/// The only legal values for the wFlags parameter is INVOKE_PROPERTYPUT or INVOKE_PROPERTYPUTREF.
///
/// If INVOKE_PROPERTYPUTREF is passed in then PutField just assigns the value of the variant that is passed in to the
/// field using normal coercion rules.
///
///
/// If INVOKE_PROPERTYPUT is passed in then specific rules apply. If the field is declared as a class that derives from IDispatch
/// and the field's value is NULL then an error will be returned. If the field's value is not NULL then the variant will be
/// passed to the default property supported by the object referenced by the field. If the field is not declared as a class
/// derived from IDispatch then an error will be returned. If the field is declared as a variant of type VT_Dispatch then
/// the default value of the object is assigned to the field. Otherwise, the variant's value is assigned to the field.
///
///
///
/// The pointer to an instance of the record.
///
///
/// The name of the field of the record.
///
///
/// The pointer to the variant.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-putfield
void PutField(uint wFlags, IntPtr pvData, [MarshalAs(UnmanagedType.LPWStr)] string szFieldName, [In, MarshalAs(UnmanagedType.Struct)] ref object pvarField);
///
///
/// Passes ownership of the data to the assigned field by placing the actual data into the field. PutFieldNoCopy is useful
/// for saving resources because it allows you to place your data directly into a record field. PutFieldNoCopy differs
/// from PutField because it does not copy the data referenced by the variant.
///
///
///
/// The only legal values for the wFlags parameter is INVOKE_PROPERTYPUT or INVOKE_PROPERTYPUTREF.
///
///
/// An instance of the record described by IRecordInfo.
///
///
/// The name of the field of the record.
///
///
/// The variant to be put into the field.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-putfieldnocopy
void PutFieldNoCopy(uint wFlags, IntPtr pvData, [MarshalAs(UnmanagedType.LPWStr)] string szFieldName, [In, MarshalAs(UnmanagedType.Struct)] ref object pvarField);
///
/// Gets the names of the fields of the record.
///
///
/// The number of names to return.
///
///
/// The name of the array of type BSTR.
/// If the rgBstrNames parameter is NULL, then pcNames is returned with the number of field names.
///
/// It the rgBstrNames parameter is not NULL, then the string names contained in rgBstrNames are returned. If the number of names
/// in pcNames and rgBstrNames are not equal then the lesser number of the two is the number of returned field names. The caller
/// needs to free the BSTRs inside the array returned in rgBstrNames.
///
///
///
///
/// The caller should allocate memory for the array of BSTRs. If the array is larger than needed, set the unused portion to 0.
///
/// On return, the caller will need to free each contained BSTR using SysFreeString.
/// In case of out of memory, pcNames points to error code.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-getfieldnames
void GetFieldNames(ref uint pcNames, [In, Out, MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.BStr, SizeParamIndex = 0)] string[] rgBstrNames);
///
/// Determines whether the record that is passed in matches that of the current record information.
///
///
/// The information of the record.
///
///
///
///
/// Return code
/// Description
///
/// -
/// TRUE
/// The record that is passed in matches the current record information.
///
/// -
/// FALSE
/// The record that is passed in does not match the current record information.
///
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-ismatchingtype
[PreserveSig] [return: MarshalAs(UnmanagedType.Bool)] bool IsMatchingType([In] IRecordInfo pRecordInfo);
///
/// Allocates memory for a new record, initializes the instance and returns a pointer to the record.
///
///
/// This method returns a pointer to the created record.
///
///
/// The memory is set to zeros before it is returned.
/// The records created must be freed by calling RecordDestroy.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recordcreate
[PreserveSig] IntPtr RecordCreate();
///
/// Creates a copy of an instance of a record to the specified location.
///
///
/// An instance of the record to be copied.
///
///
/// The new record with data copied from pvSource.
///
///
/// The records created must be freed by calling RecordDestroy.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recordcreatecopy
void RecordCreateCopy(IntPtr pvSource, out IntPtr ppvDest);
///
/// Releases the resources and deallocates the memory of the record.
///
///
/// An instance of the record to be destroyed.
///
///
/// RecordClear is called to release the resources held by the instance of a record without deallocating memory.
///
/// Note This method can only be called on records allocated through RecordCreate and RecordCreateCopy. If you allocate
/// the record yourself, you cannot call this method.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/oaidl/nf-oaidl-irecordinfo-recorddestroy
void RecordDestroy(IntPtr pvRecord);
}
}
}