Class: ExternalAddress

• Inheritance
• Description
• Related information
• Class protocol
  • instance creation
  • queries
• Instance protocol
  • Compatibility-Squeak
  • accessing
  • comparing
  • converting
  • printing & storing
  • private-accessing
• Examples

Inheritance:

   Object
   |
   +--ExternalAddress
      |
      +--OSHandle

Package:

stx:libbasic

Category:

System-Support

Version:

rev: 1.25 date: 2010/04/08 11:57:19

user: cg

file: ExternalAddress.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

Instances of this class represent external (non-Smalltalk) addresses.
They are only useful to represent handles as returned by C functions
as smalltalk objects. 
For example, Window- or WidgetIDs (which are actually 32 bit pointers) could be represented this way
(better create a handle-subclass for it, to care for proper finalization).
(you should not use SmallIntegers for this, since they can only represent 31
 bits; LargeIntegers could be used in theory, but it is not a very good style
 to do so, since it makes things a bit cryptic - having ExternalAddresses
 around makes things pretty clear in inspectors etc.).

There is not much you can do with ExternalAddresses on the smalltalk level;
creation/use should be done in primitive C-code via 
   __MKEXTERNALADDRESS(voidPtr) and __ExternalAddressVal(obj).

ExternallAddresses are much like ExternalBytes - however, the latter
allow you to access bytes via indexed at:/at:put: messages.
ExternalAddresses do not allow such accesses (they are meant to remain anonymous, opaque handles).
Also, memory blocks which are freeable should be represented as ExternalBytes.

Related information:

    ByteArray
    ExternalBytes
    ExternalFunction
    [how to write primitive code]

Class protocol:

 newAddress: addr

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned.

 pointerSize

answer the size in bytes of a pointer

Instance protocol:

 beNull

 address

return the start address as an integer

 instVarAt: index

redefined to suppress direct access to my address, which is a non-object

 instVarAt: index put: newAddress

redefined to suppress direct access to my address, which is a non-object

 = anExternalAddress

return true, if two externalAddress instance represent the same
C pointer

 hash

return a number useful for hashing

 asExternalAddress

convert to an ExternalAddress.
Useful to convert subclasses

 asExternalBytes

return an ExternalBytes object pointing to where the receiver points to.
Use of this is not recommended; primitives which return externalAddresses
dont think that access to the memory is required/useful, while primitives
which do think so should return an externalBytes instance right away.

 copyCStringFromHeap

 printOn: aStream

return a printed representation of the receiver

 setAddress: anInteger

set the address

 setAddressFromBytes: aByteArray

set the address from a pointer to which we have a pointer to

Examples: