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