author | Jan Vrany <jan.vrany@fit.cvut.cz> |
Thu, 31 Jan 2013 16:54:54 +0000 | |
branch | jv |
changeset 18022 | f23232c2eaef |
parent 17911 | a99f15c5efa5 |
parent 14726 | af723d15ccf8 |
child 18120 | e3a375d5f6a8 |
permissions | -rw-r--r-- |
9343 | 1 |
" |
2 |
COPYRIGHT (c) 2006 by eXept Software AG |
|
9350 | 3 |
All Rights Reserved |
9343 | 4 |
|
5 |
This software is furnished under a license and may be used |
|
6 |
only in accordance with the terms of that license and with the |
|
7 |
inclusion of the above copyright notice. This software may not |
|
8 |
be provided or otherwise made available to, or used by, any |
|
9 |
other person. No title to or ownership of the software is |
|
10 |
hereby transferred. |
|
11 |
" |
|
12 |
"{ Package: 'stx:libbasic' }" |
|
13 |
||
9350 | 14 |
ExternalBytes subclass:#ExternalStructure |
9343 | 15 |
instanceVariableNames:'' |
16 |
classVariableNames:'' |
|
17 |
poolDictionaries:'' |
|
18 |
category:'System-Support' |
|
19 |
! |
|
20 |
||
21 |
ExternalStructure class instanceVariableNames:'cType' |
|
22 |
||
23 |
" |
|
24 |
No other class instance variables are inherited by this class. |
|
25 |
" |
|
26 |
! |
|
27 |
||
28 |
!ExternalStructure class methodsFor:'documentation'! |
|
29 |
||
30 |
copyright |
|
31 |
" |
|
32 |
COPYRIGHT (c) 2006 by eXept Software AG |
|
9350 | 33 |
All Rights Reserved |
9343 | 34 |
|
35 |
This software is furnished under a license and may be used |
|
36 |
only in accordance with the terms of that license and with the |
|
37 |
inclusion of the above copyright notice. This software may not |
|
38 |
be provided or otherwise made available to, or used by, any |
|
39 |
other person. No title to or ownership of the software is |
|
40 |
hereby transferred. |
|
41 |
" |
|
42 |
! |
|
43 |
||
44 |
documentation |
|
45 |
" |
|
46 |
Instances of this class represent external (non-Smalltalk) data, |
|
47 |
typically C-structs or C++ instances. |
|
9350 | 48 |
They are only useful to represent handles as returned by C functions as smalltalk objects. |
9343 | 49 |
|
50 |
ExternallStructures are much like ExternalBytes - however, the latter |
|
51 |
allow you to access bytes via indexed at:/at:put: messages, whilst instances of subclasses of me |
|
52 |
allow access via the corresponding getter/setter methods of my C-type. |
|
53 |
||
14726 | 54 |
Usage: normally (within exept), these are to be used with the ctype framework, which parses |
55 |
c header files and generates structure descriptions (ctypes). |
|
56 |
However, this class can also be used wthout such type descriptions, by subclassing it |
|
57 |
and redefining sizeof (to return the size in bytes of the structure) and getters |
|
58 |
(as 'self longAt:idx', unsignedLOngAt:idx, etc.). |
|
59 |
||
9343 | 60 |
[author:] |
14726 | 61 |
Claus Gittinger |
9343 | 62 |
|
63 |
[see also:] |
|
14726 | 64 |
ExternalBytes ExternalAddress |
65 |
( how to write primitive code :html: programming/primitive.html ) |
|
9343 | 66 |
" |
67 |
! ! |
|
68 |
||
18022
f23232c2eaef
Merged 639f76c24201 and f297241056ce (branch default - CVS HEAD)
Jan Vrany <jan.vrany@fit.cvut.cz>
diff
changeset
|
69 |
|
9387 | 70 |
!ExternalStructure class methodsFor:'instance creation'! |
71 |
||
72 |
fromExternalAddress:anExternalAddress |
|
73 |
^ self new fromExternalAddress:anExternalAddress |
|
14725 | 74 |
! |
75 |
||
76 |
new |
|
77 |
"allocate some memory usable for data; |
|
78 |
the memory is not controlled by the garbage collector. |
|
79 |
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails). |
|
80 |
||
81 |
Use this, if you have to pass a block of bytes to some |
|
82 |
external destination (such as a C function) which does not copy the |
|
83 |
data, but instead keeps a reference to it. For example, many functions |
|
84 |
which expect strings simply keep a ref to the passed string - for those, |
|
85 |
an ST/X string-pointer is not the right thing to pass, since ST/X objects |
|
86 |
may change their address. |
|
87 |
||
88 |
DANGER ALERT: the memory is NOT automatically freed until it is either |
|
89 |
MANUALLY freed (see #free) or the returned externalBytes object |
|
90 |
is unprotected or the classes releaseAllMemory method is called." |
|
91 |
||
92 |
^ super new:(self sizeof) |
|
93 |
||
94 |
"Modified: / 20-12-2010 / 16:22:51 / cg" |
|
95 |
! |
|
96 |
||
97 |
unprotectedNew |
|
98 |
"allocate some memory usable for data; |
|
99 |
the memory is under the control of the garbage collector. |
|
100 |
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails). |
|
101 |
||
102 |
DANGER ALERT: the memory block as allocated will be automatically freed |
|
103 |
as soon as the reference to the returned externalBytes object |
|
104 |
is gone (by the next garbage collect). |
|
105 |
If the memory has been passed to a C-function which |
|
106 |
remembers this pointer, bad things may happen ...." |
|
107 |
||
108 |
^ super unprotectedNew:(self sizeof) |
|
9387 | 109 |
! ! |
110 |
||
18022
f23232c2eaef
Merged 639f76c24201 and f297241056ce (branch default - CVS HEAD)
Jan Vrany <jan.vrany@fit.cvut.cz>
diff
changeset
|
111 |
|
9343 | 112 |
!ExternalStructure class methodsFor:'queries'! |
113 |
||
114 |
cType |
|
115 |
^ cType |
|
14725 | 116 |
! |
117 |
||
118 |
sizeof |
|
119 |
"the sizeof my instances in bytes" |
|
120 |
||
121 |
cType notNil ifTrue:[ |
|
122 |
^ cType sizeof |
|
123 |
]. |
|
124 |
self subclassResponsibility |
|
9343 | 125 |
! ! |
126 |
||
18022
f23232c2eaef
Merged 639f76c24201 and f297241056ce (branch default - CVS HEAD)
Jan Vrany <jan.vrany@fit.cvut.cz>
diff
changeset
|
127 |
|
9387 | 128 |
!ExternalStructure methodsFor:'private'! |
129 |
||
130 |
fromExternalAddress:anExternalAddress |
|
131 |
self setAddress:(anExternalAddress address) size:(anExternalAddress size). |
|
132 |
! ! |
|
133 |
||
18022
f23232c2eaef
Merged 639f76c24201 and f297241056ce (branch default - CVS HEAD)
Jan Vrany <jan.vrany@fit.cvut.cz>
diff
changeset
|
134 |
|
9343 | 135 |
!ExternalStructure class methodsFor:'documentation'! |
136 |
||
137 |
version |
|
14726 | 138 |
^ '$Header: /cvs/stx/stx/libbasic/ExternalStructure.st,v 1.5 2013-01-28 18:04:13 cg Exp $' |
139 |
! |
|
140 |
||
141 |
version_CVS |
|
142 |
^ '$Header: /cvs/stx/stx/libbasic/ExternalStructure.st,v 1.5 2013-01-28 18:04:13 cg Exp $' |
|
17865 | 143 |
! |
144 |
||
145 |
version_SVN |
|
17911 | 146 |
^ '$Id: ExternalStructure.st 10761 2012-01-19 11:46:00Z vranyj1 $' |
9343 | 147 |
! ! |
14725 | 148 |