DkmProcess Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
DkmProcess represents a target process which is being debugged. The debugger debugs processes, so this is the basic unit of debugging. A DkmProcess can represent a system process or a virtual process such as minidumps.
public ref class DkmProcess : Microsoft::VisualStudio::Debugger::DkmDataContainer[System.Runtime.InteropServices.Guid("a6eaf62b-6db1-4f38-6359-46e9262d7a0a")]
public class DkmProcess : Microsoft.VisualStudio.Debugger.DkmDataContainer[<System.Runtime.InteropServices.Guid("a6eaf62b-6db1-4f38-6359-46e9262d7a0a")>]
type DkmProcess = class
inherit DkmDataContainerPublic Class DkmProcess
Inherits DkmDataContainer- Inheritance
- Attributes
Properties
| BaseDebugMonitorId |
DkmBaseDebugMonitorId identifies the base debug monitor used to inspect and control the debugged process. For example, DkmBaseDebugMonitorId.WindowsProcess is used for processes debugged by the Win32 debugging API and DkmBaseDebugMonitorId.DumpFile is used for minidumps. |
| Connection |
This represents a connection between the monitor and the IDE. It can either be a local connection if the monitor is running in the same process as the IDE, or it can be a remote connection. In the monitor process, there is only one connection. |
| DebugLaunchSettings |
Settings supplied during a start debugging operation from a project system or other caller of LaunchDebugTargets (or various other start debugging APIs). |
| EngineSettings |
Contains the session-wide debug settings. There is one instance of this object per engine Guid (ex: one instance for COMPlusOnlyEng2, one instance for COMPlusNativeEng). |
| IsAppPackage |
True if the process belongs to a Windows Store app package or Windows Phone app package. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). |
| IsMultiArch | |
| IsNativeDebuggingEnabled |
When true, the debugger will attempt to debug native code - it will stop on native exceptions, load symbols, display native frames on the call stack, bind and hit breakpoints, and leave native threads stopped while in break state. |
| IsUnloaded |
Returns true if a 'unloaded' event has been raised for this object (example: DkmThread::Unload is called) or if the object has been closed. Note that care must be used when checking this status as, without synchronization, the returned status may no longer be accurate the instruction after it is read. (Inherited from DkmDataContainer) |
| LivePart |
[Optional] Information relevant to a running process. For example, this Part will NOT be present for minidumps. |
| Path |
Full path to the starting executable of the process. |
| StartMethod |
StartMethod describes how the debug engine started debugging this process. |
| SystemInformation |
Contains information about the computer system that this process is running under. If this process is running under WOW (32-bit emulation on a 64-bit OS) this information will be for the 32-bit subsystem rather than the 64-bit subsystem. |
| UniqueId |
Guid which uniquely identifies this process object. This Guid value is the same as the Guid exposed at the SDM layer (IDebugProcess2::GetProcessId) and at the automation layer. |
Methods
| AbortingFuncEvalExecution(DkmFuncEvalFlags) |
AbortingFuncEvalExecution is called by the runtime debug monitor when aborting a function evaluation. AbortingFuncEvalExecution will update the internal state of the DkmProcess object so the stopping event manager will allow two stopping events through: a function evaluation complete breakpoint or an async break. |
| AddExceptionTrigger(DkmWorkList, Guid, DkmExceptionTrigger, DkmCompletionRoutine<DkmAddExceptionTriggerAsyncResult>) |
Adds an exception trigger so that ExceptionTriggerHit events will be sent when the exception trigger has been met. If there is already an exception triggered defined for this {SourceId, DkmExceptionTrigger} tuple then the existing trigger will be modified with the new settings. For example, if a component defines a trigger to stop when an access violation exception is thrown and later sets a trigger to fire when any Win32 exception goes unhandled, then the access violation trigger will be removed. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. |
| AddExceptionTrigger(Guid, DkmExceptionTrigger) |
Adds an exception trigger so that ExceptionTriggerHit events will be sent when the exception trigger has been met. If there is already an exception triggered defined for this {SourceId, DkmExceptionTrigger} tuple then the existing trigger will be modified with the new settings. For example, if a component defines a trigger to stop when an access violation exception is thrown and later sets a trigger to fire when any Win32 exception goes unhandled, then the access violation trigger will be removed. |
| AllocateVirtualMemory(UInt64, Int32, Int32, Int32) |
Reserves and/or commits a region of memory within the virtual address space of the target process. The function initializes the memory it allocates to zero, unless MEM_RESET is used. For additional information, see the VirtualAlloc Win32 API in MSDN. |
| AsyncBreak(Boolean) |
This method will tell the debug monitors to asynchronously break execution of the debuggee process. An AsyncBreakComplete event is sent after the operation is complete. |
| BeforeStopDebugging() |
Handler which is notified before the target process is terminated or detached. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| ClearAllGPUMemoryAccessWarnings() |
Disables all active GPU memory access warnings. |
| ClearExceptionTriggers(Guid) |
Removes all the exception triggers which have been set with a particular SourceId. After this method returns, the exception triggers will no longer raise ExceptionTriggerHit events. Exception triggers are automatically cleared when the DkmProcess object is closed. |
| Create(DkmTransportConnection, String, Guid, DkmStartMethod, DkmEngineSettings, DkmDebugLaunchSettings, DkmSystemInformation, Guid, Boolean, Boolean, Boolean, DkmProcess+Live, DkmDataItem) | |
| Create(DkmTransportConnection, String, Guid, DkmStartMethod, DkmEngineSettings, DkmDebugLaunchSettings, DkmSystemInformation, Guid, Boolean, Boolean, DkmProcess+Live, DkmDataItem) |
Creates a new process object. This method is called from the base debug monitor on the event thread as part of the processing of IDkmStartDebuggingOperations.AttachToProcess or IDkmStartDebuggingOperations.ResumeDebuggedProcess. This method will send a ProcessCreate event. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). |
| Create(DkmTransportConnection, String, Guid, DkmStartMethod, DkmEngineSettings, DkmDebugLaunchSettings, DkmSystemInformation, Guid, Boolean, DkmProcess+Live, DkmDataItem) |
Creates a new process object. This method is called from the base debug monitor on the event thread as part of the processing of IDkmStartDebuggingOperations.AttachToProcess or IDkmStartDebuggingOperations.ResumeDebuggedProcess. This method will send a ProcessCreate event. Location constraint: API must be called from a Monitor component (component level < 100,000). |
| CreateNativeInstructionAddress(UInt64) |
Resolves a CPU instruction to a native module, and returns a DkmNativeInstructionAddress to represent this CPU instruction. If the instruction pointer is not within a module, a DkmUnknownInstructionAddress object is returned instead. |
| Detach() |
This method is called to tell the monitor to detach from the target process. This will trigger a ProcessExit event to be sent on the event thread. |
| Disassemble(DkmInstructionAddress, UInt32) |
Disassemble an address range in the debuggee process. Location constraint: API must be called from an IDE component (component level > 100,000). |
| FindNativeModule(UInt64) |
Resolves a virtual address to a native module. If the virtual address is not within a module, null is returned (S_FALSE return code in native). Disabled modules will not be returned. |
| FindNativeModule(UInt64, Boolean) |
Resolves a virtual address to a native module. If the virtual address is not within a module, null is returned (S_FALSE return code in native). |
| FindProcess(Guid) |
Find a DkmProcess object. If no object with the given input key is present, FindProcess will fail. |
| FindProcessSnapshot(UInt32) |
Find a DkmProcessSnapshot element within this DkmProcess. If no element with the given input key is present, FindProcessSnapshot will fail. This API was introduced in Visual Studio 15 Update 3 (DkmApiVersion.VS15Update3). |
| FindRuntimeInstance(DkmRuntimeInstanceId) |
Find a DkmRuntimeInstance element within this DkmProcess. If no element with the given input key is present, FindRuntimeInstance will fail. |
| FindSystemThread(Int32) |
Find a DkmThread element within this DkmProcess. If no element with the given input key is present, FindSystemThread will fail. If an object is found, it will always contain the 'System' Part. |
| FreeVirtualMemory(UInt64, Int32, Int32) |
Releases and/or decommits a region of memory within the virtual address space of the target process. For additional information, see the VirtualFree Win32 API in MSDN. |
| GetComputeKernels() |
GetComputeKernels enumerates the DkmGPUComputeKernel elements of this DkmProcess object. |
| GetDataItem<T>() |
Gets the instance of 'T' which has been added to this container instance. If this container does not contain a 'T', this function will return null. (Inherited from DkmDataContainer) |
| GetDumpExePath() |
Returns the path to the primary executable in the minidump being debugged. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). |
| GetDumpSaveTime() | |
| GetEndingTimeContext() |
Gets the time context representing the ending position of the trace. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview). |
| GetGPUBreakpointBehavior() |
Get the breakpoint behavior of the process. |
| GetHandleCount() |
Obtains the number of active handles in the process. |
| GetInstructionAddress(DkmInstructionAddress, Int32) |
Returns the address of the kth instruction relative to a starting address. For constant length instruction sets, this is simple arithmetic. For variable length instruction sets, reverse-disassembly is required to obtain this address. Location constraint: API must be called from an IDE component (component level > 100,000). |
| GetInstructionAddress(DkmWorkList, DkmInstructionAddress, Int32, DkmCompletionRoutine<DkmGetRelativeInstructionAddressAsyncResult>) |
Returns the address of the kth instruction relative to a starting address. For constant length instruction sets, this is simple arithmetic. For variable length instruction sets, reverse-disassembly is required to obtain this address. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. Location constraint: API must be called from an IDE component (component level > 100,000). |
| GetInstructionAddress(DkmWorkList, UInt64, DkmCompletionRoutine<DkmGetInstructionAddressAsyncResult>) |
Resolves a CPU InstructionAddress to a DkmInstructionAddress. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. Location constraint: API must be called from an IDE component (component level > 100,000). |
| GetManagedStowedException() |
Get the managed stowed exception from a dump. This will return S_FALSE if there is no managed stowed exception. This API was introduced in Visual Studio 12 Update 3 (DkmApiVersion.VS12Update3). |
| GetMemoryReadTime(UInt64, UInt32, DkmMemoryTimeFlags) |
Called to find out what time relative to the current process time a value from a memory read is resolved from. This API was introduced in Visual Studio 15 Update 8 (DkmApiVersion.VS15Update8). |
| GetNativeRuntimeInstance() |
Provides access to the DkmRuntimeInstance which is for the naive code within a process. There is exactly one DkmRuntimeInstance for a process. |
| GetNativeStowedException() |
Get the native stowed exception from a dump. This will return S_FALSE if there is no native stowed exception. This API was introduced in Visual Studio 12 Update 3 (DkmApiVersion.VS12Update3). |
| GetPendingBreakpoints() |
GetPendingBreakpoints enumerates the DkmPendingBreakpoint elements of this DkmProcess object. |
| GetProcesses() |
GetProcesses enumerates all the created DkmProcess objects. |
| GetProcessExecuteDirection() |
Gets a value indicating whether the process is running in the forward or reverse direction. This method is only implemented for time travelling processes. This API was introduced in Visual Studio 15 Update 8 (DkmApiVersion.VS15Update8). |
| GetProcessorArchitecture(UInt64, DkmProcessorArchitecture) | |
| GetProcessSnapshots() |
GetProcessSnapshots enumerates the DkmProcessSnapshot elements of this DkmProcess object. This API was introduced in Visual Studio 15 Update 3 (DkmApiVersion.VS15Update3). |
| GetRunningTime() |
Obtains the number of clock cycles that the debuggee has been running since ResetRunningTime() was last called. |
| GetRuntimeFunctionResolutionRequests() |
GetRuntimeFunctionResolutionRequests enumerates the DkmRuntimeFunctionResolutionRequest elements of this DkmProcess object. |
| GetRuntimeInstances() |
GetRuntimeInstances enumerates the DkmRuntimeInstance elements of this DkmProcess object. |
| GetSerializedProcessInfo() | |
| GetSourceSnapshot() |
Get the source snapshot object for the debugged process. The debugged process must represent snapshots. This API was introduced in Visual Studio 15 Update 3 (DkmApiVersion.VS15Update3). |
| GetStowedExceptions() |
Get the stowed exceptions from a dump. This API was introduced in Visual Studio 12 Update 3 (DkmApiVersion.VS12Update3). |
| GetSystemThreads() |
Provides the list of active system threads in the process. Threads which are not system threads (DkmThread::System is null) or have been unloaded, will not be present in this collection. |
| GetTargetCompositionServices(DkmTargetCompositionScenario, Object) |
Gets the IDebugServiceManager for the corresponding scenario, which can be used to access Target Composition based extensions. Location constraint: Target composition interfaces cannot be marshalled across machine, but are safe to use if available. This API was introduced in Visual Studio 16 Update 5 (DkmApiVersion.VS16Update5). |
| GetThreads() |
GetThreads enumerates the DkmThread elements of this DkmProcess object. |
| InvisibleWriteMemory(UInt64, Byte[]) |
Write memory to the target process, but hide the write from calls to ReadMemory. This API may be used to patch instructions or data within the target process to implement debugger features. Before data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for write access, and if it is not accessible, the function raises an E_INVALID_MEMORY_ADDRESS error. |
| IsLoadComplete() |
Returns true if once all the initial module loads/thread creates have been sent for all the runtimes present when we started debugging the process. Note that this definition may be different from the Win32 Debug API definition of load complete since other runtime instances may need additional time to load. This API was introduced in Visual Studio 12 Update 2 (DkmApiVersion.VS12Update2). |
| IsStopped() |
This method allows a component to determined if the process is considered stopped by the Dispatcher. This method does not need to be called from within an interface method which requires the target process to be stopped, but it may be helpful during operations which may be called from run mode. |
| LocateBinary(String, String, String, UInt32, UInt32) |
This method will search the local disk and any configured symbol servers for a binary that matches the parameters. The path to this file on the local disk is returned. If the file was on a symbol server, it is downloaded to a cache and the local path is returned. |
| OnAsyncBreakComplete(DkmAsyncBreakStatus, DkmThread) |
Raise a AsyncBreakComplete event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller. |
| OnEntryPoint(DkmThread) |
Raise a EntryPoint event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller. |
| OnHiddenEntryPoint(DkmThread) |
Raise a HiddenEntryPoint event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| OnInstructionPatchInserted(UInt64, Byte[]) |
Method called by the base debug monitor to inform other components that the instruction memory of the target process was modified. Currently, this is only used for breakpoint insertion. Location constraint: API must be called from a Monitor component (component level < 100,000). |
| OnInstructionPatchRemoved(UInt64, Byte[]) |
Method called by the base debug monitor to inform other components that the instruction memory of the target process was restored to its original state. Currently, this is only used for breakpoint removal. Location constraint: API must be called from a Monitor component (component level < 100,000). |
| OnLoadComplete() |
This method is called by the process's base debug monitor to raise a LoadComplete event. LoadComplete is issued after DkmModuleInstance objects have been created for the initial set of modules in the process, and generally the initial set of threads have also been created. The load complete event may be deferred by a runtime debug monitor using DkmLoadCompleteEventDeferral.Add, in which case this method will immediately complete. Otherwise, this method will send the event to all components which implement the event sync interface. Control will return once all components have been notified. This method may only be called by the component which created the object. |
| OnProcessSnapshotAdded(DkmProcessSnapshot) |
Handler which is notified after a process snapshot is taken for the given process. This API was introduced in Visual Studio 15 Update 6 (DkmApiVersion.VS15Update6). |
| OnProcessSnapshotRemoved(DkmProcessSnapshot) |
Handler which is notified after a process snapshot is removed from the given process. This API was introduced in Visual Studio 15 Update 6 (DkmApiVersion.VS15Update6). |
| OnTraceTimeContextSet(DkmTraceTimeContext, DkmTraceTimeContext, DkmTraceTimeContext, DkmThread) |
Raise a TraceTimeContextSet event. Components which implement the event sink interface will receive the event notification. Control will return once all components have been notified. This method may only be called by the component which created the object. This API was introduced in Visual Studio 16 Update 2 (DkmApiVersion.VS16Update2). |
| QueryPerformanceCounters(DkmWorkList, DkmCompletionRoutine<DkmPerformanceCountersAsyncResult>) |
Asynchronous Method to obtain the timing data from the IDkmPerformanceMeasurementDispatcherService gathered from events emitted by the runtimes in the process. This is called asynchronously because obtaining the debugger overhead can be very expensive. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| ReadMemory(UInt64, DkmReadMemoryFlags, Byte[]) |
Read the memory of the target process. |
| ReadMemory(UInt64, DkmReadMemoryFlags, Void*, Int32) |
Read the memory of the target process. |
| ReadMemoryString(UInt64, DkmReadMemoryFlags, UInt16, Int32) |
Reads a null-terminated string from the target process process's memory. This can be used to read an ANSI or Unicode (UTF-8, UTF-16 or UTF-32) strings. |
| RemoveDataItem<T>() |
Remove the instance of 'T' from this container. It is usually unnecessary to call this method as a data container will automatically be emptied when the object is closed. (Inherited from DkmDataContainer) |
| RemoveExceptionTrigger(DkmWorkList, Guid, DkmExceptionTrigger, DkmCompletionRoutine<DkmRemoveExceptionTriggerAsyncResult>) |
Removes an exception trigger previously set. Note that the processing stage is ignored and does not need to match the value originally provided. This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| RemoveExceptionTrigger(Guid, DkmExceptionTrigger) |
Removes an exception trigger previously set. Note that the processing stage is ignored and does not need to match the value originally provided. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| RemoveSnapshotById(UInt32) |
Remove the process snapshots for this process. This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5). |
| RemoveSnapshots() |
Remove the process snapshots for this process. This API was introduced in Visual Studio 15 Update 3 (DkmApiVersion.VS15Update3). |
| SearchRuntimeFunctionTable(UInt64, UInt64) |
The method will return the contents of the IMAGE_RUNTIME_FUNCTION_ENTRY for an address if possible. For searching static entries, callers should call the equivalent method on DkmNativeModuleInstance. |
| SetCoreDumpParserTargetCompositionServices(Object) | |
| SetDataItem<T>(DkmDataCreationDisposition, T) |
Place a new item in the data container. (Inherited from DkmDataContainer) |
| SetDetachUnavailable(Int32) |
Called by a component to indicate that detach is not allowed on the process. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM). |
| SetGPUMemoryAccessWarning(Int32, Boolean) |
Enables / disables a particular GPU memory access warning. |
| SetProcessExecuteDirection(DkmProcessExecuteDirection) |
Sets the processes execution direction. The direction can be forward or reverse. This method is only implemented for time travelling processes. This API was introduced in Visual Studio 15 Update 8 (DkmApiVersion.VS15Update8). |
| SetRunningTime(UInt64) |
Sets the running time counter to the specified value. |
| StoppingEventProcessingBegin(Boolean) |
StoppingEventProcessingBegin is called by the base debug monitor on the event thread. It notifies the Dispatcher that the target process is stopped and may have reached a stopping event. For example, the Win32 base debug monitor calls this whenever it receives an EXCEPTION_DEBUG_EVENT from the operating system. This method updates the internal state of the DkmProcess object so that stopping events are allowed to be sent. |
| StoppingEventProcessingContinue() |
StoppingEventProcessingContinue is called by the base debug monitor on the event thread. This method is called after all stopping events within the current batch have been issued (ex: called DkmRuntimeBreakpoint.OnHit). This method will notify components which have implemented a stopping event notification interface and will call into the execution manager to slip the process to a safe point. The base debug monitor must call StoppingEventProcessingContinue after any successful call to StoppingEventProcessingBegin. the base debug monitor after it has issued all stopping events. A base debug monitor should expect to be reentrantly called while it is in this method. |
| TakeSnapshot(UInt64, DkmThread) |
Take a snapshot of the debuggee. Location constraint: Server. This API was introduced in Visual Studio 15 Update 3 (DkmApiVersion.VS15Update3). |
| TakeSnapshotWithException(UInt64, DkmExceptionInformation) |
Take a snapshot of the debuggee. Location constraint: Server. This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5). |
| Terminate(Int32) |
This method is called to tell the monitor to terminate the target process. This will trigger a ProcessExit event to be sent on the event thread. |
| TryLocateBinary(String, String, String, UInt32, UInt32) |
Called to initiate locating of binaries whose images might not have previously found or attempted to be loaded. This method will search the local disk and any configured symbol servers for a binary that matches the parameters. The path to this file on the local disk is returned. If the file was on a symbol server, it is downloaded to a cache and the local path is returned. This API was introduced in Visual Studio 11 Update 1 (DkmApiVersion.VS11FeaturePack1). |
| Unload(Int32) |
ProcessExit is sent by the dispatcher when DkmProcess::Unload is invoked by the monitor. This method may only be called by the component which created the object. |
| VolatileReadMemory(UInt64, Byte[]) |
Read memory from the target process. This method differs from 'ReadMemory' in that this method can be called at any time (not just when the target is stopped) and the debugger will not try to cache the result of this operation. |
| VolatileReadMemory(UInt64, Void*, Int32) |
Read memory from the target process. This method differs from 'ReadMemory' in that this method can be called at any time (not just when the target is stopped) and the debugger will not try to cache the result of this operation. |
| VolatileWriteMemory(UInt64, Byte[]) |
Write to the memory of the target process. This method differs from 'WriteMemory' in that this method can be called at any time (not just when the target is stopped) and the debugger will not try to cache the result of this operation. If any memory cannot be written to, an E_INVALID_MEMORY_ADDRESS error will be raised. Because the memory write may occur from run mode, this failure may happen after the copy operation has already begun, and thus may lead to memory corruption in the target process. For this reason, this function must be used with care, and failures may be fatal. |
| WaitForPausingEventProcessingComplete(Int32, Boolean) |
This method can be called from a monitor component to wait for any non-stopping with pause event handling, as well as any IDkmProcessContinueNotification processing that is currently happening to finish. Among other things, this can be helpful when attempting to abort func-evals by making sure that the target process has an opportunity to run. Note that this method doesn't provide any guarantee that there will not immediately be more pausing events, so code shouldn't assume that after returning from this API no stopping event processing is happening. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 15 Update 6 (DkmApiVersion.VS15Update6). |
| WriteDump(DkmDumpType, String, DkmThread) |
This method will write out a memory dump of the process to the path specified. |
| WriteMemory(UInt64, Byte[]) |
Writes memory to the target process. Before data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for write access, and if it is not accessible, the function raises an E_INVALID_MEMORY_ADDRESS error. |