1BZ::Client::Bug::AttachUmseenrt(C3o)ntributed Perl DocumBeZn:t:aCtliioennt::Bug::Attachment(3)
2
3
4

NAME

6       BZ::Client::Bug::Attachment - Client side representation of an
7       Attachment to a Bug in Bugzilla
8

VERSION

10       version 4.4004
11

SYNOPSIS

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
17        my $client = BZ::Client->new(
18                               url       => $url,
19                               user      => $user,
20                               password  => $password
21                           );
22
23        my $comments = BZ::Client::Bug::Attachment->get( $client, $ids );
24

CLASS METHODS

26       This section lists the class methods, which are available in this
27       module.
28
29   get
30       It allows you to get data about attachments, given a list of bugs
31       and/or attachment ids.
32
33       Note: Private attachments will only be returned if you are in the
34       insidergroup or if you are the submitter of the attachment.
35
36       Actual Bugzilla API method is "attachments".
37
38       History
39
40       Added in Bugzilla 3.6.
41
42       Parameters
43
44       Note: At least one of "ids" or "attachment_ids" is required.
45
46       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
50       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
54       attachment_ids
55           attachment_ids (array) - An array of integer attachment ID's.
56
57       Returns
58
59       A hash containing two items is returned:
60
61       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
66           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
70       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
75       The return value looks like this:
76
77        {
78            bugs => {
79                1345 => [
80                    { (attachment) },
81                    { (attachment) }
82                ],
83                9874 => [
84                    { (attachment) },
85                    { (attachment) }
86                ],
87            },
88
89            attachments => {
90                234 => { (attachment) },
91                123 => { (attachment) },
92            },
93        }
94
95       An "attachment" as shown above is an object instance of this package.
96
97       Errors
98
99       100 - Invalid Bug Alias
100           If you specified an alias and there is no bug with that alias.
101
102       101 - Invalid Bug ID
103           The "bug_id" you specified doesn't exist in the database.
104
105       102 - Access Denied
106           You do not have access to the "bug_id" you specified.
107
108       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
113   add
114       This allows you to add an attachment to a bug in Bugzilla.
115
116       Actual Bugzilla API method is "add_attachment".
117
118       History
119
120       Added in Bugzilla 4.0.
121
122       The return value has changed in Bugzilla 4.4.
123
124       Parameters
125
126       An instance of this package or a hash containing:
127
128       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
132       data
133           data (string or base64) Mostly Required - The content of the
134           attachment.
135
136           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
139           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
143       file_name
144           file_name (string) Required - The "file name" that will be
145           displayed in the UI for this attachment.
146
147           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
152           Failures to open the file (for anyreason) will be silently ignored
153           and the file_name parameter will not be touched.
154
155       summary
156           summary (string) Required - A short string describing the
157           attachment.
158
159       content_type
160           content_type (string) Required - The MIME type of the attachment,
161           like text/plain or image/png.
162
163       comment
164           comment (string) - A comment to add along with this attachment.
165
166       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
172           Defaults to False if not specified.
173
174       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
179           Defaults to False if not specified.
180
181       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
187           name
188               name (string) - The name of the flag type.
189
190           type_id
191               type_id (int) - THe internal flag type ID.
192
193           status
194               status (string) - The flags new status  (i.e. "?", "+", "-" or
195               "X" to clear a flag).
196
197           requestee
198               requestee (string) - The login of the requestee if the flag
199               type is requestable to a specific user.
200
201       Returns
202
203       An array of the attachment ID's created.
204
205       Errors
206
207       100 - Invalid Bug Alias
208           If you specified an alias and there is no bug with that alias.
209
210       101 - Invalid Bug ID
211           The "bug_id" you specified doesn't exist in the database.
212
213       102 - Access Denied
214           You do not have access to the "bug_id" you specified.
215
216       129 - Flag Status Invalid
217           The flag status is invalid.
218
219       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
223       131 - Flag not Requestable from Specific Person
224           You can't ask a specific person for the flag.
225
226       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
230       134 - Inactive Flag Type
231           The flag type is inactive and cannot be used to create new flags.
232
233       600 - Attachment Too Large
234           You tried to attach a file that was larger than Bugzilla will
235           accept.
236
237       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
242       603 - File Name Not Specified
243           You did not specify a valid for the "file_name" argument.
244
245       604 - Summary Required
246           You did not specify a value for the "summary" argument.
247
248       606 - Empty Data
249           You set the "data" field to an empty string.
250
251   render
252       Returns the HTML rendering of the provided comment text.
253
254       Actual Bugzilla API method is "render_comment".
255
256       Note: this all takes place on your Bugzilla server.
257
258       History
259
260       Added in Bugzilla 5.0.
261
262       Parameters
263
264       text
265           text (string) Required - Text comment text to render
266
267       id  id The ID of the bug to render the comment against.
268
269       Returns
270
271       The HTML rendering
272
273       Errors
274
275       100 - Invalid Bug Alias
276           If you specified an alias and there is no bug with that alias.
277
278       101 - Invalid Bug ID
279           The "bug_id" you specified doesn't exist in the database.
280
281       102 - Access Denied
282           You do not have access to the "bug_id" you specified.
283
284   update
285       This allows you to update attachment metadata in Bugzilla.
286
287       Actual Bugzilla API method is "update_attachments".
288
289       History
290
291       Added in Bugzilla 5.0.
292
293       Parameters
294
295       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
299       file_name
300           file_name (string) Required - The "file name" that will be
301           displayed in the UI for this attachment.
302
303       summary
304           summary (string) Required - A short string describing the
305           attachment.
306
307       comment
308           comment (string) - A comment to add along with this attachment.
309
310       content_type
311           content_type (string) -  The MIME type of the attachment, like
312           "text/plain" or "image/png".
313
314       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
320       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
325       is_obsolete
326           is_obsolete (boolean) - True if the attachment is obsolete, False
327           otherwise.
328
329       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
335           name
336               name (string) - The name of the flag type.
337
338           type_id
339               type_id (int) - THe internal flag type id.
340
341           status
342               status (string) - The flags new status  (i.e. "?", "+", "-" or
343               "X" to clear a flag).
344
345           requestee
346               requestee (string) - The login of the requestee if the flag
347               type is requestable to a specific user.
348
349           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
353           new new (boolean) - Set to true if you specifically want a new flag
354               to be created.
355
356       Returns
357
358       An array of hashes with the following fields:
359
360       id  id (int) The id of the attachment that was updated.
361
362       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
368       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
373           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
378           removed
379               removed (string) - The values that were removed from this
380               field.
381
382       Here is an example of what a return value might look like:
383
384        [
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
401       Errors
402
403       100 - Invalid Bug Alias
404           If you specified an alias and there is no bug with that alias.
405
406       101 - Invalid Bug ID
407           The bug_id you specified doesn't exist in the database.
408
409       102 - Access Denied
410           You do not have access to the "bug_id" you specified.
411
412       129 - Flag Status Invalid
413           The flag status is invalid.
414
415       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
419       131 - Flag not Requestable from Specific Person
420           You can't ask a specific person for the flag.
421
422       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
426       134 - Inactive Flag Type
427           The flag type is inactive and cannot be used to create new flags.
428
429       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
434       603 - File Name Not Specified
435           You did not specify a valid for the "file_name" argument.
436
437       604 - Summary Required
438           You did not specify a value for the "summary" argument.
439
440   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
448       Creates a new instance with the given details. Doesn't actually touch
449       your Bugzilla Server - see "add" for that.
450

INSTANCE METHODS

452       This section lists the modules instance methods.
453
454   bug_id
455       bug_id (int) - The ID of the bug that this attachment is on when
456       reading
457
458       bug_id (int or string) - The ID or alias of the bug to append a
459       attachment to when writing. Required.
460
461   data
462       data (base64 or string) The content of the attachment.
463
464       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
467       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. Here
469       is an example.
470
471        my $data = $attachment->data();
472        my $file_content_base64_encoded = $data->base64();
473        my $original_file_content = $data->raw();
474
475       Required, Read and Write.
476
477   file_name
478       file_name (string) The "file name" that will be displayed in the UI for
479       this attachment.
480
481       Required, Read and Write.
482
483   summary
484       summary (string) A short string describing the attachment.
485
486       Required, Read and Write.
487
488   content_type
489       content_type (string) The MIME type of the attachment, like
490       "text/plain" or "image/png".
491
492       Required, Read and Write.
493
494   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
498       Only useful when adding attachments.
499
500       body
501           body (string) The body of the comment.
502
503       is_markdown
504           is_markdown (boolean) If set to true, the comment has Markdown
505           structures; otherwise, it is an ordinary text.
506
507   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
511   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
515   is_obsolete
516       is_obsolete (boolean) - True if the attachment is obsolete, False
517       otherwise.
518
519   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
525       Read and Write.
526
527       id  id (name) The ID of the flag.
528
529       name
530           name (string) The name flag type.
531
532           Read and Write.
533
534       type_id
535           type_id (int) The internal flag type ID.
536
537           Read and Write.
538
539       creation_date
540           creation_date (DateTime) The timestamp when this flag was
541           originally created.
542
543           Read only.
544
545       modification_date
546           modification_date (DateTime) The timestamp when the flag was last
547           modified.
548
549           Read only.
550
551       status
552           status (string) The flags new status (i.e. "?", "+", "-" or "X" to
553           clear a flag).
554
555           Read and Write.
556
557       setter
558           setter (string) The login name of the user who created or last
559           modified the flag.
560
561           Read only.
562
563       requestee
564           requestee (string) The login of the requestee if the flag type is
565           requestable to a specific user.
566
567   size
568       size (int) The length (in bytes) of the attachment.
569
570       Read only.
571
572   creation_time
573       creation_time (DateTime) The time the attachment was created.
574
575       Read only.
576
577   last_change_time
578       last_change_time (DateTime) The last time the attachment was modified.
579
580   attachment_id
581       attachment_id (int) The numeric id of the attachment.
582
583   creator
584       creator (string) The login name of the user that created the
585       attachment.
586

AUTHORS

588       •   Dean Hamstead <dean@bytefoundry.com.au>
589
590       •   Jochen Wiedmann <jochen.wiedmann@gmail.com>
591
593       This software is copyright (c) 2021 by Dean Hamstad.
594
595       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.
597
598
599
600perl v5.36.0                      2023-01-20    BZ::Client::Bug::Attachment(3)
Impressum