org.eclipse.platform/org.eclipse.debug.core/3.14.100 : org/eclipse/debug/core/model/IMemoryBlockExtension.java

IMemoryBlockExtension

http://www.eclipse.org/platform: Debug Core (Eclipse Foundation)

Eclipse Public License - v 2.0

Copyright (c) 2004, 2006 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2004, 2006 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.debug.core.model;

import java.math.BigInteger;

import org.eclipse.debug.core.DebugException;

Extensions to IMemoryBlock. Allows for bytes to be accessed in a larger address space, and for state information to be provided for each byte.  Clients may optionally implement this interface when providing implementations of IMemoryBlock. 
See Also: MemoryByte
Since: 3.1/**
 * Extensions to {@link org.eclipse.debug.core.model.IMemoryBlock}. Allows
 * for bytes to be accessed in a larger address space, and for state information
 * to be provided for each byte.
 * <p>
 * Clients may optionally implement this interface when providing implementations of
 * {@link org.eclipse.debug.core.model.IMemoryBlock}.
 * </p>
 * @since 3.1
 * @see org.eclipse.debug.core.model.MemoryByte
 */
public interface IMemoryBlockExtension extends IMemoryBlock {

	Returns the expression used to create this memory block. An expression can
be used as name for a memory block and typically represents an expression
used to compute a base address for a memory block.
Returns: the expression used to create this memory block/**
	 * Returns the expression used to create this memory block. An expression can
	 * be used as name for a memory block and typically represents an expression
	 * used to compute a base address for a memory block.
	 *
	 * @return the expression used to create this memory block
	 */
	String getExpression();

	Returns the base address of this memory block as a big integer. The
address is in terms of addressable units.
Throws: DebugException – if unable to retrieve the base address
Returns: the base address of this memory block/**
	 * Returns the base address of this memory block as a big integer. The
	 * address is in terms of addressable units.
	 *
	 * @return the base address of this memory block
	 * @throws DebugException if unable to retrieve the base address
	 */
	BigInteger getBigBaseAddress() throws DebugException;

	Returns the hard start address of this memory block as a big integer, or
null if none. A null start address indicates that
memory may be retrieved at any address less than this memory block's base
address.
Throws: DebugException – if unable to retrieve the start address of this memory block.
Returns: the hard start address of this memory block or null/**
	 * Returns the hard start address of this memory block as a big integer, or
	 * <code>null</code> if none. A <code>null</code> start address indicates that
	 * memory may be retrieved at any address less than this memory block's base
	 * address.
	 *
	 * @return the hard start address of this memory block or <code>null</code>
	 * @throws DebugException if unable to retrieve the start address of this memory block.
	 */
	BigInteger getMemoryBlockStartAddress() throws DebugException;

	Returns the hard end address of this memory block as a big integer, or
null if none. A null end address indicates that
memory may be retrieved from any positive offset relative to the base address
of this memory block.
Throws: DebugException – if unable to retrieve the end address of this memory block.
Returns: the hard end address of this memory block or null/**
	 * Returns the hard end address of this memory block as a big integer, or
	 * <code>null</code> if none. A <code>null</code> end address indicates that
	 * memory may be retrieved from any positive offset relative to the base address
	 * of this memory block.
	 *
	 * @return the hard end address of this memory block or <code>null</code>
	 * @throws DebugException if unable to retrieve the end address of this memory block.
	 */
	BigInteger getMemoryBlockEndAddress() throws DebugException;

	Returns the length of this memory block, or -1 if unbounded.
Returns "end address - start address"  for a memory block with a fixed
length (i.e. when both start and end address are known).
Returns -1 for an unbounded memory block (i.e. when start or end address is
null).
Throws: DebugException – if unable to retrieve the length of this memory block.
Returns: length of this memory block or -1 if unbounded/**
	 * Returns the length of this memory block, or -1 if unbounded.
	 * Returns "end address - start address"  for a memory block with a fixed
	 * length (i.e. when both start and end address are known).
	 * Returns -1 for an unbounded memory block (i.e. when start or end address is
	 * <code>null</code>).
	 *
	 * @return length of this memory block or -1 if unbounded
	 * @throws DebugException if unable to retrieve the length of this memory block.
	 */
	BigInteger getBigLength() throws DebugException;

	Returns the address size of this memory block in number of bytes. The address
size indicates the number of bytes used to construct an address.
Throws: DebugException – if unable to retrieve the address size
Returns: address size in number of bytes/**
	 * Returns the address size of this memory block in number of bytes. The address
	 * size indicates the number of bytes used to construct an address.
	 *
	 * @return address size in number of bytes
	 * @throws DebugException if unable to retrieve the address size
	 */
	int getAddressSize() throws DebugException;

	Returns whether the base address of this memory block can be modified.
Throws: DebugException – is unable to determine if base address modification is supported
Returns: whether the base address of this memory block can be modified/**
	 * Returns whether the base address of this memory block can be modified.
	 *
	 * @return whether the base address of this memory block can be modified
	 * @throws DebugException is unable to determine if base address modification is supported
	 */
	boolean supportBaseAddressModification() throws DebugException;

	Returns whether this memory block manages the change state of its bytes.

If a memory block manages changes the memory block is responsible for
setting the CHANGED state of its MemoryByte's
returned from getBytesFromAddress and
getBytesFromOffset. The changed state of a byte should
be updated each time a thread suspends in a memory block's target.

Returns: whether this memory block manages the change state of its bytes/**
	 * Returns whether this memory block manages the change state of its bytes.
	 * <p>
	 * If a memory block manages changes the memory block is responsible for
	 * setting the <code>CHANGED</code> state of its <code>MemoryByte</code>'s
	 * returned from <code>getBytesFromAddress</code> and
	 * <code>getBytesFromOffset</code>. The changed state of a byte should
	 * be updated each time a thread suspends in a memory block's target.
	 * </p>
	 * @return whether this memory block manages the change state of its bytes
	 */
	boolean supportsChangeManagement();

	Sets the base address of this memory block to the given address.
Params: address – new base address
Throws: DebugException – if unable to modify the base address, or modification
 of the base address fails/**
	 * Sets the base address of this memory block to the given address.
	 *
	 * @param address new base address
	 * @throws DebugException if unable to modify the base address, or modification
	 *  of the base address fails
	 */
	void setBaseAddress(BigInteger address) throws DebugException;

	Returns bytes from this memory block based on the base address and
addressable size of this memory block.

A memory block may be asked to retrieve bytes beyond it's start
or end address. If a memory block is unable to retrieve memory outside
these boundaries, implementations should return memory bytes with
the READABLE bit turned off for each byte outside
the of the accessible range. An exception should not be thrown in this
case.

Params: unitOffset – zero based offset into this memory block at which to start
 retrieving bytes in terms of addressable units. Client should retrieve
 memory starting from "base address + offset".
addressableUnits – the number of addressable units to retrieve
Throws: DebugException – if unable to retrieve the specified bytes due to
 a failure communicating with the target
See Also: MemoryByte
Returns: an array of bytes from this memory block based on the given offset
 and number of units. The size of the array returned must to be equal to
 units * getAddressableSize()./**
	 * Returns bytes from this memory block based on the base address and
	 * addressable size of this memory block.
	 * <p>
	 * A memory block may be asked to retrieve bytes beyond it's start
	 * or end address. If a memory block is unable to retrieve memory outside
	 * these boundaries, implementations should return memory bytes with
	 * the <code>READABLE</code> bit turned off for each byte outside
	 * the of the accessible range. An exception should not be thrown in this
	 * case.
	 * </p>
	 * @param unitOffset zero based offset into this memory block at which to start
	 *  retrieving bytes in terms of addressable units. Client should retrieve
	 *  memory starting from "base address + offset".
	 * @param addressableUnits the number of addressable units to retrieve
	 * @return an array of bytes from this memory block based on the given offset
	 *  and number of units. The size of the array returned must to be equal to
	 *  <code>units</code> * <code>getAddressableSize()</code>.
	 * @throws DebugException if unable to retrieve the specified bytes due to
	 *  a failure communicating with the target
	 * @see MemoryByte
	 */
	MemoryByte[] getBytesFromOffset(BigInteger unitOffset, long addressableUnits) throws DebugException;

	Returns bytes from this memory block based on the given address and the
addressable size of this memory block.

A memory block may be asked to retrieve bytes beyond it's start
or end address. If a memory block is unable to retrieve memory outside
these boundaries, implementations should return memory bytes with
the READABLE bit turned off for each byte outside
the of the accessible range. An exception should not be thrown in this
case.

Params: address – address at which to begin retrieving bytes in terms
 of addressable units
units – is the number of addressable units of memory to retrieve
Throws: DebugException – if unable to retrieve the specified bytes due to
 a failure communicating with the target
See Also: MemoryByte
Returns: an array of bytes from this memory block based on the given address
 and number of units. The size of the array returned must to be equal to
 units * getAddressableSize()./**
	 * Returns bytes from this memory block based on the given address and the
	 * addressable size of this memory block.
	 * <p>
	 * A memory block may be asked to retrieve bytes beyond it's start
	 * or end address. If a memory block is unable to retrieve memory outside
	 * these boundaries, implementations should return memory bytes with
	 * the <code>READABLE</code> bit turned off for each byte outside
	 * the of the accessible range. An exception should not be thrown in this
	 * case.
	 * </p>
	 * @param address address at which to begin retrieving bytes in terms
	 *  of addressable units
	 * @param units is the number of addressable units of memory to retrieve
	 * @return an array of bytes from this memory block based on the given address
	 *  and number of units. The size of the array returned must to be equal to
	 *  <code>units</code> * <code>getAddressableSize()</code>.
	 * @throws DebugException if unable to retrieve the specified bytes due to
	 *  a failure communicating with the target
	 * @see MemoryByte
	 */
	MemoryByte[] getBytesFromAddress(BigInteger address, long units) throws DebugException;

	Sets bytes in this memory block at the specified offset within this memory block to
the specified bytes. The offset is zero based. After successfully modifying the
specified bytes, a debug event should be fired with a kind of CHANGE.
Params: offset – the zero based offset at which to set the new value.  Modify
the memory starting from base address + offset.
bytes – replacement bytes
Throws: DebugException – if this method fails.  Reasons include:
Failure communicating with the debug target.  The DebugException's
status code contains the underlying exception responsible for
the failure.
This memory block does not support value modification
The specified offset is greater than or equal to the length
  of this memory block, or the number of bytes specified goes
  beyond the end of this memory block (index of out of range)
See Also: DebugEvent/**
	 * Sets bytes in this memory block at the specified offset within this memory block to
	 * the specified bytes. The offset is zero based. After successfully modifying the
	 * specified bytes, a debug event should be fired with a kind of <code>CHANGE</code>.
	 *
	 * @param offset the zero based offset at which to set the new value.  Modify
	 * the memory starting from base address + offset.
	 * @param bytes replacement bytes
	 * @exception DebugException if this method fails.  Reasons include:
	 * <ul><li>Failure communicating with the debug target.  The DebugException's
	 * status code contains the underlying exception responsible for
	 * the failure.</li>
	 * <li>This memory block does not support value modification</li>
	 * <li>The specified offset is greater than or equal to the length
	 *   of this memory block, or the number of bytes specified goes
	 *   beyond the end of this memory block (index of out of range)</li>
	 * </ul>
	 * @see org.eclipse.debug.core.DebugEvent
	 */
	void setValue(BigInteger offset, byte[] bytes) throws DebugException;

	Connects the given client to this memory block. Allows a memory block
to know when it is being monitored. Has no effect if an identical
client is already connected.

Memory blocks supporting change management may selectively turn off
change management when no clients are connected, for reasons of
efficiency. Clients that require access to change state information
are required to connect to a memory block before change information
is considered to be valid.

Params: client – the client to connect/**
	 * Connects the given client to this memory block. Allows a memory block
	 * to know when it is being monitored. Has no effect if an identical
	 * client is already connected.
	 * <p>
	 * Memory blocks supporting change management may selectively turn off
	 * change management when no clients are connected, for reasons of
	 * efficiency. Clients that require access to change state information
	 * are required to connect to a memory block before change information
	 * is considered to be valid.
	 * </p>
	 * @param client the client to connect
	 */
	void connect(Object client);

	Disconnects the given client from this memory block. Has no effect if
an identical client is not already connected.
Params: client – the client to disconnect/**
	 * Disconnects the given client from this memory block. Has no effect if
	 * an identical client is not already connected.
	 *
	 * @param client the client to disconnect
	 */
	void disconnect(Object client);

	Returns the possibly empty list of clients currently connected to this
memory block.
Returns: the possibly empty list of clients currently connected to this
memory block/**
	 * Returns the possibly empty list of clients currently connected to this
	 * memory block.
	 *
	 * @return the possibly empty list of clients currently connected to this
	 * memory block
	 */
	Object[] getConnections();

	Dispose this memory block. Connected clients are disconnected.
Throws: DebugException – if the memory block cannot be disposed./**
	 * Dispose this memory block. Connected clients are disconnected.
	 * @throws DebugException if the memory block cannot be disposed.
	 */
	void dispose() throws DebugException;

	Returns the origin of this memory block.
Returns: the origin of this memory block/**
	 * Returns the origin of this memory block.
	 *
	 * @return the origin of this memory block
	 */
	IMemoryBlockRetrieval getMemoryBlockRetrieval();

	Returns this memory block's addressable size in number of bytes. The addressable size
of memory block indicates the minimum number of bytes that can be retrieved as
a single unit.
Throws: DebugException – if the addressable size cannot be obtained.
Returns: this memory block's addressable size/**
	 * Returns this memory block's addressable size in number of bytes. The addressable size
	 * of memory block indicates the minimum number of bytes that can be retrieved as
	 * a single unit.
	 *
	 * @return this memory block's addressable size
	 * @throws DebugException if the addressable size cannot be obtained.
	 */
	int getAddressableSize() throws DebugException;
}

Throws:	DebugException – if unable to retrieve the base address
Returns:	the base address of this memory block

Throws:	DebugException – is unable to determine if base address modification is supported
Returns:	whether the base address of this memory block can be modified

Params:	address – new base address
Throws:	DebugException – if unable to modify the base address, or modification of the base address fails

Params:	unitOffset – zero based offset into this memory block at which to start retrieving bytes in terms of addressable units. Client should retrieve memory starting from "base address + offset". addressableUnits – the number of addressable units to retrieve
Throws:	DebugException – if unable to retrieve the specified bytes due to a failure communicating with the target
See Also:	MemoryByte
Returns:	an array of bytes from this memory block based on the given offset and number of units. The size of the array returned must to be equal to `units` * `getAddressableSize()`.

Params:	address – address at which to begin retrieving bytes in terms of addressable units units – is the number of addressable units of memory to retrieve
Throws:	DebugException – if unable to retrieve the specified bytes due to a failure communicating with the target
See Also:	MemoryByte
Returns:	an array of bytes from this memory block based on the given address and number of units. The size of the array returned must to be equal to `units` * `getAddressableSize()`.

Params:	offset – the zero based offset at which to set the new value. Modify the memory starting from base address + offset. bytes – replacement bytes
Throws:	DebugException – if this method fails. Reasons include: Failure communicating with the debug target. The DebugException's status code contains the underlying exception responsible for the failure. This memory block does not support value modification The specified offset is greater than or equal to the length of this memory block, or the number of bytes specified goes beyond the end of this memory block (index of out of range)
See Also:	DebugEvent

Throws:	DebugException – if the addressable size cannot be obtained.
Returns:	this memory block's addressable size

/

org.eclipse.platform/ org.eclipse.debug.core/ 3.14.100/ org/eclipse/debug/core/model/IMemoryBlockExtension.java