~ubuntu-branches/ubuntu/karmic/libtinymail/karmic : revision 1

1

2

3

<refentrytitle role="top_of_page">TnyFolderMonitor</refentrytitle>

4

5

<refmiscinfo>LIBTINYMAIL Library</refmiscinfo>

6

</refmeta>

7

8

9

<refname>TnyFolderMonitor</refname>

10

<refpurpose>A folder observer that updates lists</refpurpose>

11

12

</refnamediv>

13

14

15

<title role="synopsis.title">Synopsis</title>

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

</synopsis>

32

</refsynopsisdiv>

33

34

35

<title role="object_hierarchy.title">Object Hierarchy</title>

36

37

38

39

+----TnyFolderMonitor

40

</synopsis>

41

42

</refsect1>

43

44

45

46

47

<title role="impl_interfaces.title">Implemented Interfaces</title>

48

<para>

49

TnyFolderMonitor implements

50

51

52

</refsect1>

53

54

55

56

57

58

59

<title role="desc.title">Description</title>

60

<para>

61

A <link linkend="TnyFolderObserver"><type>TnyFolderObserver</type></link> implementation that updates <link linkend="TnyList"><type>TnyList</type></link> implementations by adding and removing <link linkend="TnyHeader"><type>TnyHeader</type></link> instances

62

</para>

63

</refsect1>

64

65

66

<title role="details.title">Details</title>

67

68

<title><anchor id="TnyFolderMonitor-struct" role="struct"/>TnyFolderMonitor</title>

69

<indexterm><primary>TnyFolderMonitor</primary></indexterm><programlisting>typedef struct _TnyFolderMonitor TnyFolderMonitor;</programlisting>

70

<para>

71

72

</para></refsect2>

73

74

<title><anchor id="tny-folder-monitor-new" role="function"/>tny_folder_monitor_new ()</title>

75

<indexterm><primary>tny_folder_monitor_new</primary></indexterm><programlisting><link linkend="TnyFolderObserver">TnyFolderObserver</link>* tny_folder_monitor_new (<link linkend="TnyFolder">TnyFolder</link> *folder);</programlisting>

76

<para>

77

Creates a folder monitor for <parameter>folder</parameter></para>

78

<para>

79

80

</para><variablelist role="params">

81

<varlistentry><term><parameter>folder</parameter> :</term>

82

<listitem><simpara> a <link linkend="TnyFolder"><type>TnyFolder</type></link> instance

83

</simpara></listitem></varlistentry>

84

<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="TnyFolderMonitor"><type>TnyFolderMonitor</type></link> instance

85

</simpara></listitem></varlistentry>

86

</variablelist></refsect2>

87

88

<title><anchor id="tny-folder-monitor-poke-status" role="function"/>tny_folder_monitor_poke_status ()</title>

89

<indexterm><primary>tny_folder_monitor_poke_status</primary></indexterm><programlisting><link linkend="void">void</link> tny_folder_monitor_poke_status (<link linkend="TnyFolderMonitor">TnyFolderMonitor</link> *self);</programlisting>

90

<para>

91

Trigger the poke method on the folder instance being monitored.

92

Also take a look at tny_folder_poke_status in <link linkend="TnyFolder"><type>TnyFolder</type></link>.</para>

93

<para>

94

95

</para><variablelist role="params">

96

97

<listitem><simpara> a <link linkend="TnyFolderMonitor"><type>TnyFolderMonitor</type></link> instance

98

</simpara></listitem></varlistentry>

99

</variablelist></refsect2>

100

101

<title><anchor id="tny-folder-monitor-add-list" role="function"/>tny_folder_monitor_add_list ()</title>

102

<indexterm><primary>tny_folder_monitor_add_list</primary></indexterm><programlisting><link linkend="void">void</link> tny_folder_monitor_add_list (<link linkend="TnyFolderMonitor">TnyFolderMonitor</link> *self,

103

104

<para>

105

Add <parameter>list</parameter> to the registered lists that are interested in changes. <parameter>list</parameter> will

106

remain referenced until it's unregisterd using tny_folder_monitor_remove_list

107

or until <parameter>self</parameter> is finalized.</para>

108

<para>

109

110

</para><variablelist role="params">

111

112

<listitem><simpara> a <link linkend="TnyFolderChange"><type>TnyFolderChange</type></link> instance

113

</simpara></listitem></varlistentry>

114

115

<listitem><simpara> a <link linkend="TnyList"><type>TnyList</type></link> instance

116

</simpara></listitem></varlistentry>

117

</variablelist></refsect2>

118

119

<title><anchor id="tny-folder-monitor-remove-list" role="function"/>tny_folder_monitor_remove_list ()</title>

120

<indexterm><primary>tny_folder_monitor_remove_list</primary></indexterm><programlisting><link linkend="void">void</link> tny_folder_monitor_remove_list (<link linkend="TnyFolderMonitor">TnyFolderMonitor</link> *self,

121

122

<para>

123

Remove <parameter>list</parameter> from the lists that are interested in changes. This will remove

124

the reference that got added when you ussed the tny_folder_monitor_add_list.</para>

125

<para>

126

127

</para><variablelist role="params">

128

129

<listitem><simpara> a <link linkend="TnyFolderChange"><type>TnyFolderChange</type></link> instance

130

</simpara></listitem></varlistentry>

131

132

<listitem><simpara> a <link linkend="TnyList"><type>TnyList</type></link> instance

133

</simpara></listitem></varlistentry>

134

</variablelist></refsect2>

135

136

<title><anchor id="tny-folder-monitor-stop" role="function"/>tny_folder_monitor_stop ()</title>

137

<indexterm><primary>tny_folder_monitor_stop</primary></indexterm><programlisting><link linkend="void">void</link> tny_folder_monitor_stop (<link linkend="TnyFolderMonitor">TnyFolderMonitor</link> *self);</programlisting>

138

<para>

139

Stop monitoring the folder. At some point in time you must perform method

140

after you used tny_folder_monitor_start (for example before unreferencing

141

<parameter>self</parameter>).

142

</para>

143

<para>

144

The reason for that is that unless you stop <parameter>self</parameter>, it would still have a

145

reference being held by the <link linkend="TnyFolder"><type>TnyFolder</type></link> instance being monitored. By stopping

146

this monitor, you explicitly ask that folder instance to unregister <parameter>self</parameter> as

147

an observer. And by that loosing that reference too.</para>

148

<para>

149

150

</para><variablelist role="params">

151

152

<listitem><simpara> a <link linkend="TnyFolderMonitor"><type>TnyFolderMonitor</type></link> instance

153

</simpara></listitem></varlistentry>

154

</variablelist></refsect2>

155

156

<title><anchor id="tny-folder-monitor-start" role="function"/>tny_folder_monitor_start ()</title>

157

<indexterm><primary>tny_folder_monitor_start</primary></indexterm><programlisting><link linkend="void">void</link> tny_folder_monitor_start (<link linkend="TnyFolderMonitor">TnyFolderMonitor</link> *self);</programlisting>

158

<para>

159

Start monitoring the folder. The starting of a monitor implies that <parameter>self</parameter>

160

will become an observer of the folder instance. This adds a reference to <parameter>self</parameter>

161

that at some point in time must be removed using tny_folder_monitor_stop.

162

</para>

163

<para>

164

This means that if you start the monitor, you must also at some point stop it.

165

</para>

166

<para>

167

Keep this in mind: monitoring means that registered lists are kept alive. A

168

list that is alive means that it's consuming memory!</para>

169

<para>

170

171

</para><variablelist role="params">

172

173

<listitem><simpara> a <link linkend="TnyFolderMonitor"><type>TnyFolderMonitor</type></link> instance

174

</simpara></listitem></varlistentry>

175

</variablelist></refsect2>

176

177

</refsect1>

178

179

180

181

182

</refentry>