--- loncom/interface/lonmsg.pm	2007/02/23 00:39:31	1.197
+++ loncom/interface/lonmsg.pm	2007/04/22 13:41:22	1.200
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Routines for messaging
 #
-# $Id: lonmsg.pm,v 1.197 2007/02/23 00:39:31 albertel Exp $
+# $Id: lonmsg.pm,v 1.200 2007/04/22 13:41:22 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -28,6 +28,37 @@
 
 package Apache::lonmsg;
 
+=pod
+
+=head1 NAME
+
+Apache::lonmsg: supports internal messaging
+
+=head1 SYNOPSIS
+
+lonmsg provides routines for sending messages.
+
+Right now, this document will cover just how to send a message, since
+it is likely you will not need to programmatically read messages,
+since lonmsg already implements that functionality.
+
+The routines used to package messages and unpackage messages are not
+only used by lonmsg when creating/extracting messages for LON-CAPA's
+internal messaging system, but also by lonnotify.pm which is available
+for use by Domain Coordinators to broadcast standard e-mail to specified
+users in their domain.  The XML packaging used in the two cases is very
+similar.  The differences are the use of <recuser>$uname</recuser> and
+<recdomain>$udom</recdomain> in stored internal messages, compared
+with <recipient username="$uname:$udom">$email</recipient> in stored
+Domain Coordinator e-mail for the storage of information about
+recipients of the message/e-mail.
+
+=head1 FUNCTIONS
+
+=over 4
+
+=cut
+
 use strict;
 use Apache::lonnet;
 use HTML::TokeParser();
@@ -256,7 +287,7 @@ sub sendnotification {
     $text=~s/\&gt\;/\>/gs;
     $text=~s/\<\/*[^\>]+\>//gs;
     my $url='http://'.
-      $Apache::lonnet::hostname{&Apache::lonnet::homeserver($touname,$toudom)}.
+	&Apache::lonnet::hostname(&Apache::lonnet::homeserver($touname,$toudom)).
       '/adm/email?username='.$touname.'&domain='.$toudom;
     my ($sendtime,$shortsubj,$fromname,$fromdomain,$status,$fromcid,
         $symb,$error) = &Apache::lonmsg::unpackmsgid($msgid);
@@ -550,12 +581,16 @@ sub user_normal_msg_raw {
        &Apache::lonnet::put
                          ('email_status',{'recnewemail'=>time},$domain,$user);
 # Into sent-mail folder unless a broadcast message or critical message
-       unless (($env{'request.course.id'}) && 
-               (($env{'form.sendmode'} eq 'group')  || 
-               (($env{'form.critmsg'}) || ($env{'form.sendbck'})) &&
-		(&Apache::lonnet::allowed('srm',$env{'request.course.id'})
-		 || &Apache::lonnet::allowed('srm',$env{'request.course.id'}.
-					     '/'.$env{'request.course.sec'})))) {
+       unless (($env{'request.course.id'}) &&
+               (($env{'form.courserecord'}) &&
+                (&Apache::lonnet::allowed('dff',$env{'request.course.id'})
+                 || &Apache::lonnet::allowed('dff',$env{'request.course.id'}.
+                  '/'.$env{'request.course.sec'}))) ||
+                (($env{'form.sendmode'} eq 'group')  ||
+                (($env{'form.critmsg'}) || ($env{'form.sendbck'})) &&
+                 (&Apache::lonnet::allowed('srm',$env{'request.course.id'})
+                 || &Apache::lonnet::allowed('srm',$env{'request.course.id'}.
+                                             '/'.$env{'request.course.sec'})))) {
            (undef,my $packed_message_no_citation) =
                &packagemsg($subject,$message,undef,$baseurl,$attachmenturl,
                            $user,$domain,$currid,undef,$crsmsgid,$symb,$error);
@@ -598,29 +633,40 @@ sub user_normal_msg_raw {
        $baseurl, $attachmenturl, $toperm, $sentmessage, $symb, $restitle, $error)>:
  Sends a message to the  $user at $domain, with subject $subject and message $message.
 
+    Additionally it will check if the user has a Forwarding address
+    set, and send the message to that address instead
+
+    returns
+      - in array context a list of results for each message that was sent
+      - in scalar context a space seperated list of results for each
+           message sent
+
 =cut
 
 sub user_normal_msg {
     my ($user,$domain,$subject,$message,$citation,$baseurl,$attachmenturl,
 	$toperm,$sentmessage,$symb,$restitle,$error)=@_;
-    my $status='';
+    my @status;
     my %userenv = &Apache::lonnet::get('environment',['msgforward'],
                                        $domain,$user);
     my $msgforward=$userenv{'msgforward'};
     if ($msgforward) {
         foreach (split(/\,/,$msgforward)) {
 	    my ($forwuser,$forwdomain)=split(/\:/,$_);
-	    $status.=
+	    push(@status,
 	        &user_normal_msg_raw($forwuser,$forwdomain,$subject,$message,
 				     $citation,$baseurl,$attachmenturl,$toperm,
-				     undef,undef,$sentmessage,undef,$symb,$restitle,$error).' ';
+				     undef,undef,$sentmessage,undef,$symb,$restitle,$error));
         }
     } else {
-	$status=&user_normal_msg_raw($user,$domain,$subject,$message,
+	push(@status,&user_normal_msg_raw($user,$domain,$subject,$message,
 				     $citation,$baseurl,$attachmenturl,$toperm,
-				     undef,undef,$sentmessage,undef,$symb,$restitle,$error);
+				     undef,undef,$sentmessage,undef,$symb,$restitle,$error));
     }
-    return $status;
+    if (wantarray) {
+        return @status;
+    }
+    return join(' ',@status);
 }
 
 sub store_sent_mail {
@@ -691,11 +737,7 @@ sub secapply {
 
 =pod 
 
-=over 4
-
-=item *
-
-decide_receiver($feedurl,$author,$question,$course,$policy,$defaultflag);
+=item * B<decide_receiver($feedurl,$author,$question,$course,$policy,$defaultflag)>:
 
 Arguments
   $feedurl - /res/ url of resource (only need if $author is true)
@@ -759,6 +801,12 @@ sub decide_receiver {
     return ($typestyle,%to);
 }
 
+=pod
+
+=back
+
+=cut
+
 1;
 __END__