Modifying Decorating messages sent

There are two main mechanisms that can be used to modify/decorate messages that are sent by DUM. Initial requests are easy to customize, as the messages are returned from the DialogUsageManger::makeXXXX methods, and can be modified before calling send. However many messages are send by dum usages automatically.

onReadyToSend

The onReadyToSend callback is called by dialog creating usages for any in-dialog messaging ie: InviteSessions and Subscriptions. onReadyToSend can be sufficient in many scenarios, but there are situations when using outbound decorators is much more powerful.

Outbound Decorators

An outbound decorator can be set on a DUM userprofile. This decorator will be invoked by the resiprocate stack just before the message is sent out on the wire. Outbound decorators are more powerful than using the onReadyToSend mechanism:

• onReadyToSend is only called for established dialogs, so logic to decorate an initial outbound request must be done after the DialogUsageManager::makeXXXX fns. Outbound decorators are invoked for every message sent out the stack.
• Outbound decorators are invoked after the transport selector is run, and the Contact and Via headers are populated by the stack. The application may require this information in order to do it's decoration.

Sample Outbound decorator to update the IP Address in the SdpContents based on the interface used to send the SIP request (from dum/test/basicClientUserAgent.cxx):

 // Used to set the IP Address in outbound SDP to match the IP address choosen by the stack to send the message on
 class SdpMessageDecorator : public MessageDecorator
 {
 public:
    virtual ~SdpMessageDecorator() {}
    virtual void decorateMessage(SipMessage &msg, 
                                 const Tuple &source,
                                 const Tuple &destination,
                                 const Data& sigcompId)
    {
       SdpContents* sdp = dynamic_cast<SdpContents*>(msg.getContents());
       if(sdp)  
       {
          // Fill in IP and Port from source
          sdp->session().connection().setAddress(Tuple::inet_ntop(source), 
                                                 source.ipVersion() == V6 ? SdpContents::IP6 : 
                                                                            SdpContents::IP4);
          sdp->session().origin().setAddress(Tuple::inet_ntop(source), 
                                             source.ipVersion() == V6 ? SdpContents::IP6 : 
                                                                        SdpContents::IP4);
          InfoLog( << "SdpMessageDecorator: src=" << source << ", dest=" << destination 
                   << ", msg=" << endl << msg.brief());
       }
    }
    virtual void rollbackMessage(SipMessage& msg) {}  // Nothing to do
    virtual MessageDecorator* clone() const { return new SdpMessageDecorator; }
 };

 // Install Sdp Message Decorator
 mProfile->setOutboundDecorator(std::make_shared<SdpMessageDecorator>());