1BZ::Client::Bug::AttachUmseenrt(C3o)ntributed Perl DocumBeZn:t:aCtliioennt::Bug::Attachment(3)
2
6 BZ::Client::Bug::Attachment - Client side representation of an
7 Attachment to a Bug in Bugzilla
8
10 version 4.4002
11
13 This class provides methods for accessing and managing attachments in
14 Bugzilla. Instances of this class are returned by
15 BZ::Client::Bug::Attachment::get.
16 my $client = BZ::Client->new(
18 url => $url,
19 user => $user,
20 password => $password
21 );
22 my $comments = BZ::Client::Bug::Attachment->get( $client, $ids );
24
26 This section lists the class methods, which are available in this
27 module.
28 get
30 It allows you to get data about attachments, given a list of bugs
31 and/or attachment ids.
32 Note: Private attachments will only be returned if you are in the
34 insidergroup or if you are the submitter of the attachment.
35 Actual Bugzilla API method is "attachments".
37 History
39 Added in Bugzilla 3.6.
41 Parameters
43 Note: At least one of "ids" or "attachment_ids" is required.
45 In addition to the parameters below, this method also accepts the
47 standard "include_fields" in BZ::Client::Bug and "exclude_fields" in
48 BZ::Client::Bug arguments.
49 ids ids (array) - An array that can contain both bug IDs and bug
51 aliases. All of the attachments (that are visible to you) will be
52 returned for the specified bugs.
53 attachment_ids
55 attachment_ids (array) - An array of integer attachment ID's.
56 Returns
58 A hash containing two items is returned:
60 bugs
62 This is used for bugs specified in "ids". This is a hash, where the
63 keys are the numeric ID's of the bugs and the value is an array of
64 attachment obejcts.
65 Note that any individual bug will only be returned once, so if you
67 specify an ID multiple times in "ids", it will still only be
68 returned once.
69 attachments
71 Each individual attachment requested in "attachment_ids" is
72 returned here, in a hash where the numeric "attachment_id" is the
73 key, and the value is the attachment object.
74 The return value looks like this:
76 {
78 bugs => {
79 1345 => [
80 { (attachment) },
81 { (attachment) }
82 ],
83 9874 => [
84 { (attachment) },
85 { (attachment) }
86 ],
87 },
88 attachments => {
90 234 => { (attachment) },
91 123 => { (attachment) },
92 },
93 }
94 An "attachment" as shown above is an object instance of this package.
96 Errors
98 100 - Invalid Bug Alias
100 If you specified an alias and there is no bug with that alias.
101 101 - Invalid Bug ID
103 The "bug_id" you specified doesn't exist in the database.
104 102 - Access Denied
106 You do not have access to the "bug_id" you specified.
107 304 - Auth Failure, Attachment is Private
109 You specified the ID of a private attachment in the
110 "attachment_ids" argument, and you are not in the "insidergroup"
111 that can see private attachments.
112 add
114 This allows you to add an attachment to a bug in Bugzilla.
115 Actual Bugzilla API method is "add_attachment".
117 History
119 Added in Bugzilla 4.0.
121 The return value has changed in Bugzilla 4.4.
123 Parameters
125 An instance of this package or a hash containing:
127 ids ids (array) Required - An array of ints and/or strings - the ID's
129 or aliases of bugs that you want to add this attachment to. The
130 same attachment and comment will be added to all these bugs.
131 data
133 data (string or base64) Mostly Required - The content of the
134 attachment.
135 The content will be base64 encoded. Of you can do it yourself by
137 providing this option as a BZ::Client::XMPRPC::base64 object.
138 What is "Mostly Required" you ask? If you provide "file_name" only,
140 this module will attempt to slurp it to provide this data
141 parameter. See "file_name" options for more details.
142 file_name
144 file_name (string) Required - The "file name" that will be
145 displayed in the UI for this attachment.
146 If no /data parameter is provided, this module will attempt to
148 open, slurp the contents of a file with path file_name, base64
149 encod that data, placed it into the /data parameter, then
150 file_name is truncted to just the files basename.
151 Failures to open the file (for anyreason) will be silently ignored
153 and the file_name parameter will not be touched.
154 summary
156 summary (string) Required - A short string describing the
157 attachment.
158 content_type
160 content_type (string) Required - The MIME type of the attachment,
161 like text/plain or image/png.
162 comment
164 comment (string) - A comment to add along with this attachment.
165 is_patch
167 is_patch (boolean) - True if Bugzilla should treat this attachment
168 as a patch. If you specify this, you do not need to specify a
169 "content_type". The "content_type" of the attachment will be forced
170 to "text/plain".
171 Defaults to False if not specified.
173 is_private
175 is_private (boolean) - True if the attachment should be private
176 (restricted to the "insidergroup"), False if the attachment should
177 be public.
178 Defaults to False if not specified.
180 flags
182 An array of hashes with flags to add to the attachment. to create a
183 flag, at least the "status" and the "type_id" or "name" must be
184 provided. An optional requestee can be passed if the flag type is
185 requestable to a specific user.
186 name
188 name (string) - The name of the flag type.
189 type_id
191 type_id (int) - THe internal flag type ID.
192 status
194 status (string) - The flags new status (i.e. "?", "+", "-" or
195 "X" to clear a flag).
196 requestee
198 requestee (string) - The login of the requestee if the flag
199 type is requestable to a specific user.
200 Returns
202 An array of the attachment ID's created.
204 Errors
206 100 - Invalid Bug Alias
208 If you specified an alias and there is no bug with that alias.
209 101 - Invalid Bug ID
211 The "bug_id" you specified doesn't exist in the database.
212 102 - Access Denied
214 You do not have access to the "bug_id" you specified.
215 129 - Flag Status Invalid
217 The flag status is invalid.
218 130 - Flag Modification Denied
220 You tried to request, grant, or deny a flag but only a user with
221 the required permissions may make the change.
222 131 - Flag not Requestable from Specific Person
224 You can't ask a specific person for the flag.
225 133 - Flag Type not Unique
227 The flag type specified matches several flag types. You must
228 specify the type id value to update or add a flag.
229 134 - Inactive Flag Type
231 The flag type is inactive and cannot be used to create new flags.
232 600 - Attachment Too Large
234 You tried to attach a file that was larger than Bugzilla will
235 accept.
236 601 - Invalid MIME Type
238 You specified a "content_type" argument that was blank, not a valid
239 MIME type, or not a MIME type that Bugzilla accepts for
240 attachments.
241 603 - File Name Not Specified
243 You did not specify a valid for the "file_name" argument.
244 604 - Summary Required
246 You did not specify a value for the "summary" argument.
247 606 - Empty Data
249 You set the "data" field to an empty string.
250 render
252 Returns the HTML rendering of the provided comment text.
253 Actual Bugzilla API method is "render_comment".
255 Note: this all takes place on your Bugzilla server.
257 History
259 Added in Bugzilla 5.0.
261 Parameters
263 text
265 text (string) Required - Text comment text to render
266 id id The ID of the bug to render the comment against.
268 Returns
270 The HTML rendering
272 Errors
274 100 - Invalid Bug Alias
276 If you specified an alias and there is no bug with that alias.
277 101 - Invalid Bug ID
279 The "bug_id" you specified doesn't exist in the database.
280 102 - Access Denied
282 You do not have access to the "bug_id" you specified.
283 update
285 This allows you to update attachment metadata in Bugzilla.
286 Actual Bugzilla API method is "update_attachments".
288 History
290 Added in Bugzilla 5.0.
292 Parameters
294 ids ids (array) - An array that can contain both bug IDs and bug
296 aliases. All of the attachments (that are visible to you) will be
297 returned for the specified bugs.
298 file_name
300 file_name (string) Required - The "file name" that will be
301 displayed in the UI for this attachment.
302 summary
304 summary (string) Required - A short string describing the
305 attachment.
306 comment
308 comment (string) - A comment to add along with this attachment.
309 content_type
311 content_type (string) - The MIME type of the attachment, like
312 "text/plain" or "image/png".
313 is_patch
315 is_patch (boolean) - True if Bugzilla should treat this attachment
316 as a patch. If you specify this, you do not need to specify a
317 "content_type". The "content_type" of the attachment will be forced
318 to "text/plain".
319 is_private
321 is_private (boolean) - True if the attachment should be private
322 (restricted to the "insidergroup"), False if the attachment should
323 be public.
324 is_obsolete
326 is_obsolete (boolean) - True if the attachment is obsolete, False
327 otherwise.
328 flags
330 An array of hashes with flags to add to the attachment. to create a
331 flag, at least the status and the type_id or name must be provided.
332 An optional requestee can be passed if the flag type is requestable
333 to a specific user.
334 name
336 name (string) - The name of the flag type.
337 type_id
339 type_id (int) - THe internal flag type id.
340 status
342 status (string) - The flags new status (i.e. "?", "+", "-" or
343 "X" to clear a flag).
344 requestee
346 requestee (string) - The login of the requestee if the flag
347 type is requestable to a specific user.
348 id id (int) - Use "id" to specify the flag to be updated. You will
350 need to specify the "id" if more than one flag is set of the
351 same name.
352 new new (boolean) - Set to true if you specifically want a new flag
354 to be created.
355 Returns
357 An array of hashes with the following fields:
359 id id (int) The id of the attachment that was updated.
361 last_change_time
363 last_change_time (DateTime) - The exact time that this update was
364 done at, for this attachment. If no update was done (that is, no
365 fields had their values changed and no comment was added) then this
366 will instead be the last time the attachment was updated.
367 changes
369 changes (hash) - The changes that were actually done on this bug.
370 The keys are the names of the fields that were changed, and the
371 values are a hash with two keys:
372 added
374 added (string) - The values that were added to this field.
375 possibly a comma-and-space-separated list if multiple values
376 were added.
377 removed
379 removed (string) - The values that were removed from this
380 field.
381 Here is an example of what a return value might look like:
383 [
385 {
386 id => 123,
387 last_change_time => '2010-01-01T12:34:56',
388 changes => {
389 summary => {
390 removed => 'Sample ptach',
391 added => 'Sample patch'
392 },
393 is_obsolete => {
394 removed => '0',
395 added => '1',
396 },
397 },
398 },
399 ]
400 Errors
402 100 - Invalid Bug Alias
404 If you specified an alias and there is no bug with that alias.
405 101 - Invalid Bug ID
407 The bug_id you specified doesn't exist in the database.
408 102 - Access Denied
410 You do not have access to the "bug_id" you specified.
411 129 - Flag Status Invalid
413 The flag status is invalid.
414 130 - Flag Modification Denied
416 You tried to request, grant, or deny a flag but only a user with
417 the required permissions may make the change.
418 131 - Flag not Requestable from Specific Person
420 You can't ask a specific person for the flag.
421 133 - Flag Type not Unique
423 The flag type specified matches several flag types. You must
424 specify the type ID value to update or add a flag.
425 134 - Inactive Flag Type
427 The flag type is inactive and cannot be used to create new flags.
428 601 - Invalid MIME Type
430 You specified a "content_type" argument that was blank, not a valid
431 MIME type, or not a MIME type that Bugzilla accepts for
432 attachments.
433 603 - File Name Not Specified
435 You did not specify a valid for the "file_name" argument.
436 604 - Summary Required
438 You did not specify a value for the "summary" argument.
439 new
441 my $comment = BZ::Client::Bug::Comment->new(
442 id => $bug_id,
443 comment => $comment,
444 is_private => 1 || 0,
445 work_time => 3.5
446 );
447 Creates a new instance with the given details. Doesn't actually touch
449 your Bugzilla Server - see "add" for that.
450
452 This section lists the modules instance methods.
453 bug_id
455 bug_id (int) - The ID of the bug that this attachment is on when
456 reading
457 bug_id (int or string) - The ID or alias of the bug to append a
459 attachment to when writing. Required.
460 data
462 data (base64 or string) The content of the attachment.
463 When writing, either provide a string (which will be "base46" encoded
465 for you) or a BZ::Client::XMLRPC::base64 object if you'd like to DIY.
466 When reading, a BZ::Client::XMLRPC::base64 object will be returned. To
468 save you the trip, this object has a "raw()" and a "base64()" method.
469 Here is an example.
470 my $data = $attachment->data();
472 my $file_content_base64_encoded = $data->base64();
473 my $original_file_content = $data->raw();
474 Required, Read and Write.
476 file_name
478 file_name (string) The "file name" that will be displayed in the UI for
479 this attachment.
480 Required, Read and Write.
482 summary
484 summary (string) A short string describing the attachment.
485 Required, Read and Write.
487 content_type
489 content_type (string) The MIME type of the attachment, like
490 "text/plain" or "image/png".
491 Required, Read and Write.
493 comment
495 comment (string or hash) A comment to add along with this attachment.
496 If "comment" is a hash, it has the following keys:
497 Only useful when adding attachments.
499 body
501 body (string) The body of the comment.
502 is_markdown
504 is_markdown (boolean) If set to true, the comment has Markdown
505 structures; otherwise, it is an ordinary text.
506 is_patch
508 is_patch (boolean) True if the attachment should be private (restricted
509 to the "insidergroup"), False if the attachment should be public.
510 is_private
512 is_private (boolean) True if the attachment is private (only visible to
513 a certain group called the "insidergroup"), False otherwise.
514 is_obsolete
516 is_obsolete (boolean) - True if the attachment is obsolete, False
517 otherwise.
518 flags
520 flags (array) An array of hashes with flags to add to the attachment.
521 to create a flag, at least the status and the type_id or name must be
522 provided. An optional requestee can be passed if the flag type is
523 requestable to a specific user.
524 Read and Write.
526 id id (name) The ID of the flag.
528 name
530 name (string) The name flag type.
531 Read and Write.
533 type_id
535 type_id (int) The internal flag type ID.
536 Read and Write.
538 creation_date
540 creation_date (DateTime) The timestamp when this flag was
541 originally created.
542 Read only.
544 modification_date
546 modification_date (DateTime) The timestamp when the flag was last
547 modified.
548 Read only.
550 status
552 status (string) The flags new status (i.e. "?", "+", "-" or "X" to
553 clear a flag).
554 Read and Write.
556 setter
558 setter (string) The login name of the user who created or last
559 modified the flag.
560 Read only.
562 requestee
564 requestee (string) The login of the requestee if the flag type is
565 requestable to a specific user.
566 size
568 size (int) The length (in bytes) of the attachment.
569 Read only.
571 creation_time
573 creation_time (DateTime) The time the attachment was created.
574 Read only.
576 last_change_time
578 last_change_time (DateTime) The last time the attachment was modified.
579 attachment_id
581 attachment_id (int) The numeric id of the attachment.
582 creator
584 creator (string) The login name of the user that created the
585 attachment.
586
588 · Dean Hamstead <dean@bytefoundry.com.au>
589 · Jochen Wiedmann <jochen.wiedmann@gmail.com>
591
593 This software is copyright (c) 2017 by Dean Hamstad.
594 This is free software; you can redistribute it and/or modify it under
596 the same terms as the Perl 5 programming language system itself.
597perl v5.28.0 2018-07-14 BZ::Client::Bug::Attachment(3)