1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::NotificationCenter</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.html" class="namespace">Poco</a></h1>
<h1 class="symbol">class NotificationCenter</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Foundation<br />
<b>Package:</b> Notifications<br />
<b>Header:</b> Poco/NotificationCenter.h</p>
<h2>Description</h2>
<div class="description">
<p>A <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> is essentially a notification dispatcher. It notifies all observers of notifications meeting specific criteria. This information is encapsulated in <a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> objects. Client objects register themselves with the notification center as observers of specific notifications posted by other objects. When an event occurs, an object posts an appropriate notification to the notification center. The notification center invokes the registered method on each matching observer, passing the notification as argument. </p>
<p>The order in which observers receive notifications is undefined. It is possible for the posting object and the observing object to be the same. The <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> delivers notifications to observers synchronously. In other words the <a href="Poco.NotificationCenter.html#8797" title="Poco::NotificationCenter::postNotification()">postNotification</a>() method does not return until all observers have received and processed the notification. If an observer throws an exception while handling a notification, the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> stops dispatching the notification and <a href="Poco.NotificationCenter.html#8797" title="Poco::NotificationCenter::postNotification()">postNotification</a>() rethrows the exception. </p>
<p>In a multithreaded scenario, notifications are always delivered in the thread in which the notification was posted, which may not be the same thread in which an observer registered itself. </p>
<p>The <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> class is basically a C++ implementation of the NSNotificationCenter class found in Apple's Cocoa (or OpenStep). </p>
<p>While handling a notification, an observer can unregister itself from the notification center, or it can register or unregister other observers. Observers added during a dispatch cycle will not receive the current notification. </p>
<p>The method receiving the notification must be implemented as </p>
<pre>void handleNotification(MyNotification* pNf);
</pre>
<p>The handler method gets co-ownership of the <a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> object and must release it when done. This is best done with an <a href="Poco.AutoPtr.html" title="class Poco::AutoPtr">AutoPtr</a>: </p>
<pre>void MyClass::handleNotification(MyNotification* pNf)
{
AutoPtr<MyNotification> nf(pNf);
...
}
</pre>
<p>Alternatively, the <a href="Poco.NObserver.html" title="class Poco::NObserver">NObserver</a> class template can be used to register a callback method. In this case, the callback method receives the <a href="Poco.Notification.html" title="class Poco::Notification">Notification</a> in an <a href="Poco.AutoPtr.html" title="class Poco::AutoPtr">AutoPtr</a> and thus does not have to deal with object ownership issues: </p>
<pre>void MyClass::handleNotification(const AutoPtr<MyNotification>& pNf)
{
...
}
</pre>
</div>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.NotificationCenter.html#8793" title="Poco::NotificationCenter::addObserver()">addObserver</a>, <a href="Poco.NotificationCenter.html#8800" title="Poco::NotificationCenter::countObservers()">countObservers</a>, <a href="Poco.NotificationCenter.html#8801" title="Poco::NotificationCenter::defaultCenter()">defaultCenter</a>, <a href="Poco.NotificationCenter.html#8799" title="Poco::NotificationCenter::hasObservers()">hasObservers</a>, <a href="Poco.NotificationCenter.html#8797" title="Poco::NotificationCenter::postNotification()">postNotification</a>, <a href="Poco.NotificationCenter.html#8795" title="Poco::NotificationCenter::removeObserver()">removeObserver</a></p>
<h2>Constructors</h2>
<h3><a name="8791">NotificationCenter</a></h3>
<p class="decl"><a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>();</p>
<div class="description">
<p>Creates the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. </p>
</div>
<h2>Destructor</h2>
<h3><a name="8792">~NotificationCenter</a></h3>
<p class="decl">~<a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>();</p>
<div class="description">
<p>Destroys the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. </p>
</div>
<h2>Member Functions</h2>
<h3><a name="8793">addObserver</a></h3>
<p class="decl">void addObserver(<br /> const <a href="Poco.AbstractObserver.html" title="class Poco::AbstractObserver">AbstractObserver</a> & observer<br />);</p>
<div class="description">
<p>Registers an observer with the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. Usage: </p>
<pre>Observer<MyClass, MyNotification> obs(*this, &MyClass::handleNotification);
notificationCenter.addObserver(obs);
</pre>
<p>Alternatively, the <a href="Poco.NObserver.html" title="class Poco::NObserver">NObserver</a> template class can be used instead of <a href="Poco.Observer.html" title="class Poco::Observer">Observer</a>. </p>
</div>
<h3><a name="8800">countObservers</a></h3>
<p class="decl">std::size_t countObservers() const;</p>
<div class="description">
<p>Returns the number of registered observers. </p>
</div>
<h3><a name="8801">defaultCenter</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> & defaultCenter();</p>
<div class="description">
<p>Returns a reference to the default <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. </p>
</div>
<h3><a name="8799">hasObservers</a></h3>
<p class="decl">bool hasObservers() const;</p>
<div class="description">
<p>Returns true if and only if there is at least one registered observer. </p>
<p>Can be used to improve performance if an expensive notification shall only be created and posted if there are any observers. </p>
</div>
<h3><a name="8797">postNotification</a></h3>
<p class="decl">void postNotification(<br /> <a href="Poco.Notification.html#8786" title="Poco::Notification::Ptr">Notification::Ptr</a> pNotification<br />);</p>
<div class="description">
<p>Posts a notification to the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. The <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a> then delivers the notification to all interested observers. If an observer throws an exception, dispatching terminates and the exception is rethrown to the caller. Ownership of the notification object is claimed and the notification is released before returning. Therefore, a call like </p>
<pre>notificationCenter.postNotification(new MyNotification);
</pre>
<p>does not result in a memory leak. </p>
</div>
<h3><a name="8795">removeObserver</a></h3>
<p class="decl">void removeObserver(<br /> const <a href="Poco.AbstractObserver.html" title="class Poco::AbstractObserver">AbstractObserver</a> & observer<br />);</p>
<div class="description">
<p>Unregisters an observer with the <a href="Poco.NotificationCenter.html" title="class Poco::NotificationCenter">NotificationCenter</a>. </p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</div>
</body>
</html>
|
