1package SyslogScan::Usage;
2
3$VERSION = 0.20;
4sub Version { $VERSION };
5
6use SyslogScan::Volume;
7
8my $SEND = 0;
9my $RECEIVE = 1;
10my $BROADCAST = 2;
11
12my @ROLE_LIST = ($BROADCAST,$SEND,$RECEIVE);
13
14use strict;
15
16sub new
17{
18    my $type = shift;
19
20    my $self = ();
21
22    my $role;
23    foreach $role (@ROLE_LIST)
24    {
25	$$self[$role] = new SyslogScan::Volume;
26    }
27    bless($self,$type);
28    return $self;
29}
30
31sub addUsage
32{
33    my $self = shift;
34    my $other = shift;
35    my $role;
36    foreach $role (@ROLE_LIST)
37    {
38	$$self[$role] -> addVolume($$other[$role]);
39    }
40}
41
42sub registerSend
43{
44    my $self = shift;
45    my $size = shift;
46
47    $self -> register($size,$SEND);
48}
49
50sub registerReceive
51{
52    my $self = shift;
53    my $size = shift;
54
55    $self -> register($size,$RECEIVE);
56}
57
58sub registerBroadcast
59{
60    my $self = shift;
61    my $size = shift;
62
63    $self -> register($size,$BROADCAST);
64}
65
66sub getBroadcastVolume
67{
68    my $self = shift;
69    return $$self[$BROADCAST] -> deepCopy();
70}
71
72sub getSendVolume
73{
74    my $self = shift;
75    return $$self[$SEND] -> deepCopy();
76}
77
78sub getReceiveVolume
79{
80    my $self = shift;
81    return $$self[$RECEIVE] -> deepCopy();
82}
83
84sub register
85{
86    my $self = shift;
87    my $size = shift;
88    my $role = shift;
89
90    defined($$self[$role]) or
91	die "illegal Role: $role";
92
93    $$self[$role] -> addSize($size);
94}
95
96sub persist
97{
98    my $self = shift;
99    my $outFH = shift;
100
101    my $role;
102    foreach $role (@ROLE_LIST)
103    {
104	$$self[$role] -> persist($outFH);
105    }
106}
107
108sub restore
109{
110    my $type = shift;
111    my $inFH = shift;
112
113    my $self = ();
114
115    my $role;
116    foreach $role (@ROLE_LIST)
117    {
118	$$self[$role] =
119	  SyslogScan::Volume -> restore($inFH);
120    }
121
122    bless($self,$type);
123
124    return $self;
125}
126
127sub dump
128{
129    my $self = shift;
130    my $retString;
131
132    my $role;
133    foreach $role (@ROLE_LIST)
134    {
135	$retString .= "\t\t". $$self[$role] -> dump();
136    }
137    return $retString."\n";
138}
139
140sub deepCopy
141{
142    my $self = shift;
143    my $copy = ();
144
145    my $role;
146    foreach $role (@ROLE_LIST)
147    {
148	$$copy[$role] = $$self[$role] -> deepCopy();
149    }
150
151    bless($copy,ref($self));
152    return $copy;
153}
154
1551;
156
157__END__
158
159=head1 NAME
160
161SyslogScan::Usage -- encapsulates the total volumes of mail broadcast,
162sent, and received through sendmail by a single user or group.
163
164SyslogScan::Volume -- encapsulates a number of messages along with a
165total number of bytes
166
167=head1 SYNOPSIS
168
169# $summary is a SyslogScan::Summary object
170
171use SyslogScan::Usage;
172my $usage = $$summary{'john_doe@foo.com'};
173$usage -> dump();
174
175use SyslogScan::Volume;
176my $broadcastVolume = $usage -> getBroadcastVolume();
177my $sendVolume = $usage -> getSendVolume();
178my $receiveVolume = $usage -> getReceiveVolume();
179
180print "John Doe sent $$sendVolume[0] messages with $$sendVolume[1] bytes\n";
181
182=head1 DESCRIPTION
183
184=head2 Broadcast, Send, and Receive
185
186Volume of messages received has the obvious meaning.  Volume of
187messages sent and volume of messages broadcast require more
188explanation.
189
190If I send out a message which has three recipients, then for the
191purposes of the SyslogScan modules, I am I<broadcasting> the message
192once, but I am I<sending> it three times.
193
194=head2 Usage methods
195
196=over 4
197
198=item new() method
199
200Creates a new, empty Usage object.
201
202=item addUsage() method and deepCopy() method
203
204   # $usage1 is 4 messages of 100 bytes Received
205   # $usage2 is 1 message of 35 bytes Received
206
207   my $usageTotal = $usage1 -> deepCopy();
208   # $usageTotal is 4 messages of 100 bytes Received
209
210   $usageTotal -> addUsage($usage2);
211   # $usageTotal is 5 messages of 135 bytes Received
212
213Note that because we used deepCopy, I<$usage1> is still 4 messages of
214100 bytes.
215
216=item registerBroadcast, registerSend, registerReceive methods
217
218    my $usage = new SyslogScan::Usage();
219    $usage -> registerSend(512);
220    $usage -> registerSend(34);
221    $usage -> registerBroadcast(34);
222    # $usage is now 2 messages, 546 bytes Sent,
223    # and 1 message, 34 bytes Broadcast
224
225=item getBroadcastVolume, getSendVolume, getReceiveVolume methods
226
227Returns deep copy of the applicable SyslogScan::Volume objects.
228
229=item static deepCopy method
230
231Returns deep copy of the whole SyslogScan::Usage object.
232
233=item static dump
234
235Returns a string containing (Message,Bytes) pairs for Broadcast, Send,
236and Receive volumes.
237
238=back
239
240=head2 Volume methods
241
242=over 4
243
244=item new() method
245
246Creates a new Volume object of 0 messages, 0 bytes.
247
248=item deepCopy() method
249
250Creates a new Volume object with the same number of messages and bytes
251as the current Volume object.
252
253=item addVolume(), addSize() methods
254
255addVolume() adds the volume of a second Volume object onto the volume
256of the current Volume object.
257
258addSize() adds on one message of the given size.
259
260    use SyslogScan::Volume;
261
262    my $volume1 = new SyslogScan::Volume();
263    $volume1 -> addSize(512);
264
265    my $volume2 = $volume1 -> deepCopy();
266    # $volume2 is 1 message, 512 bytes
267
268    $volume2 -> addSize(31);
269    # $volume2 is 2 messages, 543 bytes
270
271    $volume2 -> addVolume($volume1);
272    # $volume2 is 3 messages, 1055 bytes
273
274    $volume2 -> addVolume($volume2);
275    # $volume2 is 6 messages, 2110 bytes
276
277=item getMessageCount, getByteCount
278
279Gets the number of messages and the total number of bytes, respectively.
280
281=item dump()
282
283Returns the string "getMessageCount(),getByteCount()"
284
285=back
286
287=head2 Volume internals
288
289A Volume is simply a two-element array of ($messages, $bytes).
290
291$$volume[0] is the number of messages
292$$volume[1] is the number of bytes
293
294=head1 AUTHOR and COPYRIGHT
295
296The author (Rolf Harold Nelson) can currently be e-mailed as
297rolf@usa.healthnet.org.
298
299This code is Copyright (C) SatelLife, Inc. 1996.  All rights reserved.
300This code is free software; you can redistribute it and/or modify it
301under the same terms as Perl itself.
302
303In no event shall SatelLife be liable to any party for direct,
304indirect, special, incidental, or consequential damages arising out of
305the use of this software and its documentation (including, but not
306limited to, lost profits) even if the authors have been advised of the
307possibility of such damage.
308
309=head1 SEE ALSO
310
311L<SyslogScan::Summary>
312