1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta content="en" name="language">
<title>Magick::Exception</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link media="screen" href="../docutils-articles.css" type="text/css" rel="stylesheet">
</head>
<body>
<div class="banner">
<img src="../images/gm-107x76.png" alt="GraphicMagick logo" width="107" height="76" />
<span class="title">GraphicsMagick</span>
<form action="http://www.google.com/search">
<input type="hidden" name="domains" value="www.graphicsmagick.org" />
<input type="hidden" name="sitesearch" value="www.graphicsmagick.org" />
<span class="nowrap"><input type="text" name="q" size="25" maxlength="255" /> <input type="submit" name="sa" value="Search" /></span>
</form>
</div>
<div class="navmenu">
<ul>
<li><a href="../index.html">Home</a></li>
<li><a href="../project.html">Project</a></li>
<li><a href="../download.html">Download</a></li>
<li><a href="../README.html">Install</a></li>
<li><a href="../Hg.html">Source</a></li>
<li><a href="../NEWS.html">News</a> </li>
<li><a href="../utilities.html">Utilities</a></li>
<li><a href="../programming.html">Programming</a></li>
<li><a href="../reference.html">Reference</a></li>
</ul>
</div>
<main id="magick-exception">
<h1 class="title">Magick::Exception</h1>
<!-- -*- mode: rst -*- -->
<!-- This text is in reStucturedText format, so it may look a bit odd. -->
<!-- See http://docutils.sourceforge.net/rst.html for details. -->
<p><em>Exception</em> represents the base class of objects thrown when
Magick++ reports an error. Magick++ throws C++ exceptions synchronous
with the operation where the error occurred. This allows errors to be
trapped within the enclosing code (perhaps the code to process a
single image) while allowing the code to be written with a simple
coding style.</p>
<p>A try/catch block should be placed around any sequence of operations
which can be considered an important body of work. For example, if
your program processes lists of images and some of these images may be
defective, by placing the try/catch block around the entire sequence
of code that processes one image (including instantiating the image
object), you can minimize the overhead of error checking while
ensuring that all objects created to deal with that object are safely
destroyed (C++ exceptions unroll the stack until the enclosing try
block, destroying any objects on the stack).</p>
<p>Note that any objects allocated via 'new' with a pointer on the stack
are not automatically destroyed by unrolling the stack via a C++
exception so that it may be necessary to catch the exception at each
level, destroy any objects allocated via 'new' (or malloc()) and then
re-throw the exception. This includes constructors which might
encounter an exception while the object is being constructed and
should destroy any already-allocated data. Magick++ classes are
designed to be <strong>very</strong> tiny so it is recommended to automatically
allocate them on the stack when possible rather than via 'new'.</p>
<p>The pseudo code for the main loop of your program may look like:</p>
<pre class="literal-block"> using namespace std;
for infile in list
{
try {
// Construct an image instance first so that we don't have to worry
// about object construction failure due to a minor warning exception
// being thrown.
Magick::Image image;
// Determine if Warning exceptions are thrown.
// Use is optional. Set to true to block Warning exceptions.
image.quiet( false );
try {
// Try reading image file
image.read(infile);
}
catch( Magick::WarningCoder &warning )
{
// Process coder warning while loading file (e.g. TIFF warning)
// Maybe the user will be interested in these warnings (or not).
// If a warning is produced while loading an image, the image
// can normally still be used (but not if the warning was about
// something important!)
cerr << “Coder Warning: “ << warning.what() << endl;
}
catch( Magick::Warning &warning )
{
// Handle any other Magick++ warning.
cerr << “Warning: “ << warning.what() << endl;
}
catch( Magick::ErrorFileOpen &error )
{
// Process Magick++ file open error
cerr << “Error: “ << error.what() << endl;
continue; // Try next image.
}
try {
image.rotate(90);
image.write(“outfile”);
}
catch ( MagickExeption & error)
{
// Handle problem while rotating or writing outfile.
cerr << “Caught Magick++ exception: “ << error.what() << endl;
}
}
catch( std::exception &error )
{
// Process any other exceptions derived from standard C++ exception
cerr << “Caught C++ STD exception: “ << error.what() << endl;
}
catch( ... )
{
// Process *any* exception (last-ditch effort). There is not a lot
// you can do here other to retry the operation that failed, or exit
// the program.
}
}
The desired location and number of try/catch blocks in your program
depends how sophisticated its error handling must be. Very simple
programs may use just one try/catch block.</pre>
<p>The <em>Exception</em> class is derived from the C++ standard
<em>std::exception</em> class. This means that it contains a C++ string
containing additional information about the error (e.g to display to
the user). Obtain access to this string via the what() method. For
example:</p>
<pre class="literal-block">catch( Exception &error_ )
{
cout << "Caught exception: " << error_.what() << endl;
}</pre>
<p>The classes <em>Warning</em> and <em>Error</em> derive from the <em>Exception</em>
class. Exceptions derived from <em>Warning</em> are thrown to represent
non-fatal errors which may effect the completeness or quality of the
result (e.g. one image provided as an argument to montage is
defective). In most cases, a <em>Warning</em> exception may be ignored by
catching it immediately, processing it (e.g. printing a diagnostic)
and continuing on. Exceptions derived from <em>Error</em> are thrown to
represent fatal errors that can not produce a valid result
(e.g. attempting to read a file which does not exist).</p>
<p>The specific derived exception classes are shown in the following tables:</p>
<table>
<caption>Warning (Suspect but completed) Sub-Classes</caption>
<colgroup>
<col style="width: 35%" />
<col style="width: 65%" />
</colgroup>
<thead>
<tr><th class="head"><p>Warning</p></th>
<th class="head"><p>Warning Description</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>WarningUndefined</p></td>
<td><p>Unspecified type.</p></td>
</tr>
<tr><td><p>WarningBlob</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCache</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCoder</p></td>
<td><p>Issued by some coders.</p></td>
</tr>
<tr><td><p>WarningConfigure</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningCorruptImage</p></td>
<td><p>Issued when an image may be corrupt.</p></td>
</tr>
<tr><td><p>WarningDelegate</p></td>
<td><p>Reported by a subordinate program.</p></td>
</tr>
<tr><td><p>WarningDraw</p></td>
<td><p>Reported by the rendering subsystem.</p></td>
</tr>
<tr><td><p>WarningFileOpen</p></td>
<td><p>Reported when file could not be opened.</p></td>
</tr>
<tr><td><p>WarningImage</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningMissingDelegate</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningModule</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningMonitor</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningOption</p></td>
<td><p>Reported when an option is incorrect.</p></td>
</tr>
<tr><td><p>WarningRegistry</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningResourceLimit</p></td>
<td><p>Reported when a resource is exhausted.</p></td>
</tr>
<tr><td><p>WarningStream</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningType</p></td>
<td><p>NOT CURRENTLY USED</p></td>
</tr>
<tr><td><p>WarningXServer</p></td>
<td><p>Warnings reported by the X11 subsystem.</p></td>
</tr>
</tbody>
</table>
<table>
<caption>Error (Failed) Sub-Classes</caption>
<colgroup>
<col style="width: 33%" />
<col style="width: 67%" />
</colgroup>
<thead>
<tr><th class="head"><p>Error</p></th>
<th class="head"><p>Error Description</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>ErrorUndefined</p></td>
<td><p>Unspecified error type.</p></td>
</tr>
<tr><td><p>ErrorBlob</p></td>
<td><p>Reported by BLOB I/O subsystem.</p></td>
</tr>
<tr><td><p>ErrorCache</p></td>
<td><p>Reported by the pixel cache subsystem.</p></td>
</tr>
<tr><td><p>ErrorCoder</p></td>
<td><p>Reported by coders (image format support).</p></td>
</tr>
<tr><td><p>ErrorConfigure</p></td>
<td><p>Reported while loading configuration files.</p></td>
</tr>
<tr><td><p>ErrorCorruptImage</p></td>
<td><p>Reported when the image file is corrupt.</p></td>
</tr>
<tr><td><p>ErrorDelegate</p></td>
<td><p>Reported by a subordinate program</p></td>
</tr>
<tr><td><p>ErrorDraw</p></td>
<td><p>Reported while drawing on image.</p></td>
</tr>
<tr><td><p>ErrorFileOpen</p></td>
<td><p>Reported when the image file can not be opened.</p></td>
</tr>
<tr><td><p>ErrorImage</p></td>
<td><p>Reported while drawing.</p></td>
</tr>
<tr><td><p>ErrorMissingDelegate</p></td>
<td><p>Reported when optional add-on library or
subordinate program is missing (but is needed).</p></td>
</tr>
<tr><td><p>ErrorModule</p></td>
<td><p>Reported by the module loader subsystem.</p></td>
</tr>
<tr><td><p>ErrorMonitor</p></td>
<td><p>Reported by the progress monitor.</p></td>
</tr>
<tr><td><p>ErrorOption</p></td>
<td><p>Reported when option is malformed or out of range.</p></td>
</tr>
<tr><td><p>ErrorRegistry</p></td>
<td><p>Reported by the image/BLOB registry subsystem.</p></td>
</tr>
<tr><td><p>ErrorResourceLimit</p></td>
<td><p>Reported when a program resource is exhausted.</p></td>
</tr>
<tr><td><p>ErrorStream</p></td>
<td><p>Reported by the pixel stream subsystem.</p></td>
</tr>
<tr><td><p>ErrorType</p></td>
<td><p>Reported by the type (font) rendering subsystem.</p></td>
</tr>
<tr><td><p>ErrorXServer</p></td>
<td><p>Reported by the X11 subsystem.</p></td>
</tr>
</tbody>
</table>
<p>Note that <em>ErrorMissingDelegate</em> is a "catch-all" error reported when
GraphicsMagick is unable to figure out how to open the file.</p>
<p>Copyright © Bob Friesenhahn 1999 - 2022</p>
</main>
<hr class="docutils">
<div class="document">
<p><a href="../Copyright.html">Copyright</a> © GraphicsMagick Group 2002-2025<!--SPONSOR_LOGO--></p>
</div>
</main>
</body>
</html>
|
