lib/Net/DBus/Binding/Message/Signal.pm

   1 # -*- perl -*-
   2 #
   3 # Copyright (C) 2004-2011 Daniel P. Berrange
   4 #
   5 # This program is free software; You can redistribute it and/or modify
   6 # it under the same terms as Perl itself. Either:
   7 #
   8 # a) the GNU General Public License as published by the Free
   9 #   Software Foundation; either version 2, or (at your option) any
  10 #   later version,
  11 #
  12 # or
  13 #
  14 # b) the "Artistic License"
  15 #
  16 # The file "COPYING" distributed along with this file provides full
  17 # details of the terms and conditions of the two licenses.
  18
  19 =pod
  20
  21 =head1 NAME
  22
  23 Net::DBus::Binding::Message::Signal - a message encoding a signal
  24
  25 =head1 SYNOPSIS
  26
  27   use Net::DBus::Binding::Message::Signal;
  28
  29   my $signal = Net::DBus::Binding::Message::Signal->new(
  30       object_path => "/org/example/myobject",
  31       interface => "org.example.myobject",
  32       signal_name => "foo_changed");
  33
  34   $connection->send($signal);
  35
  36 =head1 DESCRIPTION
  37
  38 This module is part of the low-level DBus binding APIs, and
  39 should not be used by application code. No guarentees are made
  40 about APIs under the C<Net::DBus::Binding::> namespace being
  41 stable across releases.
  42
  43 This module provides a convenience constructor for creating
  44 a message representing a signal.
  45
  46 =head1 METHODS
  47
  48 =over 4
  49
  50 =cut
  51
  52 package Net::DBus::Binding::Message::Signal;
  53
  54 use 5.006;
  55 use strict;
  56 use warnings;
  57
  58 use Net::DBus;
  59 use base qw(Net::DBus::Binding::Message);
  60
  61
  62 =item my $signal = Net::DBus::Binding::Message::Signal->new(
  63       object_path => $path, interface => $interface, signal_name => $name);
  64
  65 Creates a new message, representing a signal [to be] emitted by
  66 the object located under the path given by the C<object_path>
  67 parameter. The name of the signal is given by the C<signal_name>
  68 parameter, and is scoped to the interface given by the
  69 C<interface> parameter.
  70
  71 =cut
  72
  73 sub new {
  74     my $proto = shift;
  75     my $class = ref($proto) || $proto;
  76     my %params = @_;
  77
  78     my $msg = exists $params{message} ? $params{message} :
  79         Net::DBus::Binding::Message::Signal::_create
  80         (
  81          ($params{object_path} ? $params{object_path} : die "object_path parameter is required"),
  82          ($params{interface} ? $params{interface} : die "interface parameter is required"),
  83          ($params{signal_name} ? $params{signal_name} : die "signal_name parameter is required"));
  84
  85     my $self = $class->SUPER::new(message => $msg);
  86
  87     bless $self, $class;
  88
  89     return $self;
  90 }
  91
  92
  93 1;
  94
  95 __END__
  96
  97 =back
  98
  99 =head1 AUTHOR
 100
 101 Daniel P. Berrange.
 102
 103 =head1 COPYRIGHT
 104
 105 Copyright (C) 2004-2009 Daniel P. Berrange
 106
 107 =head1 SEE ALSO
 108
 109 L<Net::DBus::Binding::Message>
 110
 111 =cut