~ctrlproxy/ctrlproxy/trunk

by ctrlproxy. (By sending the correct <quote>PASS ...</quote> line). If set to 0, the client has not been authenticated, if set to 1, the client has been successfully authenticated. A value of 2 means the client has disconnected.</para></listitem>

</varlistentry>

<varlistentry><term>struct transport_context *incoming</term>

<listitem><para>Transport context to be used to communicate with the client.</para></listitem>

</varlistentry>

<varlistentry><term>time_t connect_time</term>

<listitem><para>Contains unix timestamp of the moment the client

did its initial connect. This field is used to kick clients that have not authenticated after one minute.</para></listitem>

</varlistentry>

</variablelist>

</sect2>

<sect2><title>struct network</title>

struct network {

xmlNodePtr xmlConf;

char modes[255];

xmlNodePtr servers;

char *hostmask;

GList *channels;

char authenticated;

GList *clients;

xmlNodePtr current_server;

xmlNodePtr listen;

char *supported_modes[2];

char **features;

struct transport_context *outgoing;

struct transport_context **incoming;

};

</programlisting>

<para>Describes an IRC network that ctrlproxy is connected to.</para>

<varlistentry><term>xmlNodePtr xmlConf;</term>

<listitem><para>Points to XML node with configuration for this network.</para></listitem>

</varlistentry>

<varlistentry><term>char modes[255];</term>

<listitem><para>Array with modes of the user on this network. For modes that have been set, the index in this array has been set to 1. The rest of the array is set to 0. </para>

<para>For example, if mode <quote>i</quote>(invisible) is set on this user, <quote>modes['i']</quote> is set to 1.</para>

</listitem></varlistentry>

<varlistentry><term>xmlNodePtr servers;</term>

<listitem><para>Pointer to XML node <servers> for this server.</para></listitem></varlistentry>

<varlistentry><term>char *hostmask;</term>

<listitem><para>Hostmask that ctrlproxy uses to communicate to the server.</para></listitem>

</varlistentry>

<varlistentry><term>GList *channels;</term>

<listitem><para>List of <quote>struct channel</quote> pointers

with channels the user has joined on this network.</para></listitem>

</varlistentry>

<varlistentry><term>char authenticated;</term>

100

<listitem><para>Indicates whether the connection to this network is

101

established. It is set to true after a 004 message has been

102

received.</para></listitem>

103

</varlistentry>

104

105

<varlistentry><term>GList *clients;</term>

106

<listitem><para>List of <quote>struct client</quote> pointers

107

with all the clients that have connected to ctrlproxy

108

for this network.</para></listitem>

109

</varlistentry>

110

111

<varlistentry><term>xmlNodePtr current_server;</term>

112

<listitem><para>Pointer to XML node that contains the configuration

113

data of the current server ctrlproxy is connected to for

114

this network.</para></listitem>

115

</varlistentry>

116

<varlistentry><term>xmlNodePtr listen;</term>

117

<listitem><para>Pointer to XML node <listen>.</para></listitem>

118

</varlistentry>

119

120

<varlistentry><term>char *supported_modes[2];</term>

121

<listitem><para>Contains 2 arrays of modes that is supported by the remote server. This list is sent by the server after the connection has just been set-up.</para></listitem>

122

</varlistentry>

123

124

<varlistentry><term>char **features;</term>

125

<listitem><para>Array of options supported by the server. Same format as unix environment variables, though a value is not required.</para></listitem>

126

</varlistentry>

127

128

<varlistentry><term>struct transport_context *outgoing;</term>

129

<listitem><para>Transport context to use to communicate with the remote

130

server.</para></listitem>

131

</varlistentry>

132

133

<varlistentry><term>struct transport_context **incoming;</term>

134

<listitem><para>List with transport contexts for the clients that

135

are currently connected to ctrlproxy for this server.</para></listitem>

136

</varlistentry>

137

</variablelist>

138

</sect2>

139

140

</sect1>

141

142

<sect1><title>State data</title>

143

144

<para>This section covers everything related to the current (known) state information of the network the user is on.</para>

145

146

<sect2><title>struct nick</title>

147

148

149

struct nick {

150

char *name;

151

char mode;

152

};

153

</programlisting>

154

155

<para>Covers one nick in a certain channel. Mode is either a space, indicating

156

the user has no special rights, a '@' if the user is an operator or a '+' if

157

the user has voice.</para>

158

159

</sect2>

160

161

<sect2><title>struct channel</title>

162

163

164

struct channel {

165

xmlNodePtr xmlConf;

166

char *topic;

167

char mode;

168

char *modes[255];

169

char introduced;

170

long limit;

171

char *key;

172

GList *nicks;

173

};

174

</programlisting>

175

176

<para>Covers one channel at a certain network that the user is currently on. Here is a small list with explanation of the various fields.</para>

177

178

179

<varlistentry><term>xmlNodePtr xmlConf</term>

180

<listitem><para>Pointer to XML node describing this channel.</para></listitem>

181

</varlistentry>

182

183

184

<listitem><para>Indicates whether the channel is private or secret. </para></listitem>

185

</varlistentry>

186

187

<varlistentry><term>char *topic</term>

188

<listitem><para>Pointer to string containing the topic of this channel. NULL if no topic has been set or if the topic is unknown.</para></listitem></varlistentry>

189

190

<varlistentry><term>char *modes[255]</term>

191

<listitem><para>Modes that have been set on this channel. FIXME</para></listitem></varlistentry>

192

<varlistentry><term>char introduced</term>

193

<listitem><para>Reserved for use by replication functions. Private. Do not use.</para></listitem></varlistentry>

194

<varlistentry><term>long limit</term>

195

<listitem><para>Maximum number of users on the channel. 0 means no limit has been set.</para></listitem></varlistentry>

196

197

<listitem><para>Key users have to enter to enter the channel. If no key is required, this field is set to NULL.</para></listitem></varlistentry>

198

<varlistentry><term>GList *nicks</term>

199

<listitem><para>List of <quote>struct nick</quote>, one for each user that is joined to the channel.</para></listitem></varlistentry>

200

</variablelist>

201

202

</sect2>

203

<sect2><title>find_channel()</title>

204

205

206

struct channel *find_channel(struct network *st, char *name);

207

</programlisting>

208

209

<para>Returns a pointer to the struct of the channel with the specified name on the specified network. Returns NULL if no channel struct was found.</para>

210

211

<para>Note that this function only works for channels the user has currently used.</para>

212

213

</sect2>

214

215

216

217

218

struct nick *find_nick(struct channel *c, char *name);

219

</programlisting>

220

221

<para>Find data pointer to <quote>struct nick</quote> of the user with the specified name on the specified channel.</para>

222

223

<para>If the user was not found, NULL is returned.</para>

224

225

</sect2>

226

227

<sect2><title>gen_replication_network()</title>

228

229

230

GSList *gen_replication_network(struct network *s);

231

</programlisting>

232

233

<para>Generates double-linked list of strings that need to be send

234

to a client to give it a good view of the channels that have been joined, the users on those channels and the modes of those channels. </para>

235

236

</sect2>

237

238

<sect2><title>gen_replication_channel()</title>

239

240

241

GSList *gen_replication_channel(struct channel *s, char *hostmask, char *nick);

242

</programlisting>

243

244

<para>Generates double-linked list of strings that need to be send

245

to a client to give it a good view of a channel that ctrlproxy has joined. hostmask should be the name of the server the messages are coming from and nick the name of the user the replication is sent to.</para>

246

247

</sect2>

248

249

<sect2><title>default_replicate_function</title>

250

251

252

void default_replicate_function (struct network *, struct transport_context *);

253

extern void (*replicate_function) (struct network *, struct transport_context *);

254

</programlisting>

255

256

<para>Default replication function. What this basically does is sending

257

the strings returned by gen_replication() to the specified transport_context.</para>

258

259

</sect2>

260

</sect1>

261

262

<sect1><title>Maintaining the main process</title>

263

264

265

extern GList *networks;

266

extern xmlNodePtr xmlNode_networks, xmlNode_plugins;

267

extern GList *plugins;

268

extern xmlDocPtr configuration;

269

extern GHookList data_hook;

270

</programlisting>

271

272

<para>Pointers to various useful varables. The <parameter>xmlNode_*</parameter> variables point to

273

the <networks> and <plugins> elements in the rc file.</para>

274

275

<para><parameter>configuration</parameter> points to the top level XML document.</para>

276

277

<para><parameter>data_hook</parameter> can be used to register a function that should be called whenever ctrlproxy receives or sends IRC messages.</para>

278

279

<para><parameter>plugins</parameter> and <parameter>networks</parameter> contain

280

lists to all <quote>struct plugin</quote>s and <quote>struct network</quote>s, respectively.</para>

281

282

<sect2><title>network_add_listen()</title>

283

284

285

void network_add_listen(struct network *, xmlNodePtr);

286

</programlisting>

287

288

<para>Add listener to specified network with configuration specified

289

in xmlNodePtr.</para>

290

291

</sect2>

292

293

<sect2><title>save_configuration()</title>

294

295

296

void save_configuration();

297

</programlisting>

298

299

<para>Save the current state of the XML configuration of ctrlproxy

300

to the same file it was loaded from.</para>

301

302

</sect2>

303

304

<sect2><title>load_plugin()</title>

305

306

307

gboolean load_plugin(xmlNodePtr);

308

</programlisting>

309

310

<para>Load plugin with specified configuration. xmlNodePtr should

311

point to a <plugin> element.</para>

312

313

</sect2>

314

315

<sect2><title>unload_plugin()</title>

316

317

318

gboolean unload_plugin(struct plugin *);

319

</programlisting>

320

321

<para>Try to unload the specified plugin. Not all plugins support this at the moment. Returns TRUE if the unloading succeeded, FALSE otherwise. Failure of unloading may be caused by resources that are still in use.</para>

322

</sect2>

323

324

<sect2><title>plugin_loaded()</title>

325

326

327

gboolean plugin_loaded(char *name);

328

</programlisting>

329

330

<para>Returns TRUE if a plugin with the specified name was loaded.</para>

331

</sect2>

332

</sect1>

333

334

<sect1><title>Line parsing/creation/handling</title>

335

336

<para>These functions all have to do with manipulating line structs.

337

Pretty much all internal functions of ctrlproxy work with these

338

instead of manipulating plain strings.</para>

339

340

341

struct line {

342

enum data_direction direction;

343

int options;

344

struct network *network;

345

struct client *client;

346

const char *origin;

347

char **args; /* NULL terminated */

348

size_t argc;

349

};

350

351

/* for the options fields */

352

#define LINE_IS_PRIVATE 1

353

#define LINE_DONT_SEND 2

354

#define LINE_STOP_PROCESSING 4

355

356

enum data_direction { UNKNOWN = 0, TO_SERVER = 1, FROM_SERVER = 2 };

357

</programlisting>

358

359

360

<varlistentry><term>enum data_direction direction;</term>

361

<listitem><para>Direction of this line. A value of TO_SERVER means it's going to the server, FROM_SERVER means it's coming from a remote IRC server. UNKNOWN is used in cases where the direction is not known.</para></listitem>

362

</varlistentry>

363

<varlistentry><term>int options;</term>

364

<listitem><para>Sum of one of LINE_IS_PRIVATE, LINE_DONT_SEND and LINE_STOP_PROCESSING. LINE_IS_PRIVATE means this line was send by a client and should not be sent to the other clients. LINE_DONT_SEND should be used to tell ctrlproxy to not send this line to its destination (either client or server). LINE_STOP_PROCESSING will stop further filtering of the line.</para>

365

</listitem>

366

</varlistentry>

367

<varlistentry><term>struct network *network;</term>

368

<listitem><para>Points to the network this line came from or is going to.</para></listitem>

369

</varlistentry>

370

<varlistentry><term>struct client *client;</term>

371

<listitem><para>Points to the client this line came from, if any. Set to NULL if unknown.</para></listitem>

372

</varlistentry>

373

<varlistentry><term>const char *origin;</term>

374

<listitem><para>Hostmask of the user who sent the message. NULL if unknown.</para></listitem>

375

</varlistentry>

376

377

<listitem><para>IRC arguments/commands in an array. Last element is set to NULL.</para></listitem>

378

</varlistentry>

379

380

<listitem><para>Contains number of arguments/commands in <parameter>args</parameter>.</para></listitem>

381

</varlistentry>

382

</variablelist>

383

384

<sect2><title>linedup()</title>

385

386

387

struct line *linedup(struct line *l);

388

</programlisting>

389

<para>Duplicate the given line struct.</para>

390

391

</sect2>

392

393

<sect2><title>irc_parse_line()</title>

394

395

396

struct line * irc_parse_line(char *data);

397

</programlisting>

398

<para>Takes a string as sent by an IRC client or an IRC server and generates

399

a struct line.</para>

400

</sect2>

401

402

<sect2><title>virc_parse_line()</title>

403

404

405

struct line * virc_parse_line(char *origin, va_list ap);

406

struct line *irc_parse_line_args( char *origin, ... );

407

gboolean irc_send_args(struct transport_context *, ...);

408

</programlisting>

409

<para>Generates a line struct with the hostmask specified in <parameter>origin</parameter> or NULL if none should be set.</para>

410

411

<para>For virc_parse_line(), the <parameter>ap</parameter> should be a list of strings

412

that are each that are a seperate part of the IRC line. The last argument

413

should be NULL to indicate the end of the list.</para>

414

415

<para>irc_parse_line_args() is similar to virc_parse_line(), except that now the commands don't need to be passed in a <parameter>va_list</parameter>, but can be passed as arguments.</para>

416

417

<para>irc_send_args() sends the specified commands, terminated by a NULL to the specified transport_context.</para>

418

419

</sect2>

420

421

<sect2><title>irc_line_string()</title>

422

423

424

char *irc_line_string(struct line *l);

425

char *irc_line_string_nl(struct line *l);

426

</programlisting>

427

<para>Generate a string representation of a line struct in the format used

428

by IRC clients and servers.</para>

429

430

<para>irc_Line_string_nl() is similar to irc_line_string(), except that it

431

adds a newline and a carriage-return to the string (\r\n).</para>

432

433

</sect2>

434

435

436

437

438

char *line_get_nick(struct line *l);

439

</programlisting>

440

<para>Get the nick name of the user that sent <parameter>l</parameter> or

441

NULL if the nick name was unknown.</para>

442

443

</sect2>

444

445

446

447

448

void free_line(struct line *l);

449

</programlisting>

450

<para>Free all data associated with <parameter>l</parameter>.</para>

451

452

</sect2>

453

454

<sect2><title>irc_sendf()</title>

455

456

457

gboolean irc_sendf(struct transport_context *, char *fmt, ...);

458

struct line *irc_parse_linef( char *fmt, ... );

459

</programlisting>

460

<para>irc_sendf() sends the specified transport_context a IRC line. fmt

461

is a printf-like string and the remaining arguments correspond to

462

the data in <parameter>fmt</parameter>. See the printf manpage for details.</para>

463

464

<para>irc_parse_linef() is similar, but instead of sending the string it generates a struct line and returns it.</para>

465

466

</sect2>

467

468

469

470

471

int irc_send_line(struct transport_context *, struct line *l);

472

</programlisting>

473

<para>Send the specified line to the specified transport_context. </para>

474

475

</sect2>

476

477

<sect2><title>clients_send()</title>

478

479

480

void clients_send(struct network *, struct line *, struct transport_context *exception);

481

</programlisting>

482

<para>Send the specified line to all clients on the specified network, except for the client with transport_context <parameter>exception</parameter>. <parameter>exception</parameter> can be NULL.</para>

483

484

</sect2>

485

486

</sect1>

487

488

<sect1><title>General purpose functions</title>

489

<sect2><title>list_make_string()</title>

490

491

492

char *list_make_string(char **l);

493

</programlisting>

494

<para>Creates a string with all the elements in string array <parameter>l</parameter>, seperated by spaces. The last element in <parameter>l</parameter> should be NULL.</para>

495

496

</sect2>

497

498

<sect2><title>xmLFindChildByName()</title>

499

500

501

xmlNodePtr xmlFindChildByName(xmlNodePtr parent, const xmlChar *name);

502

</programlisting>

503

<para>Find a child node of the XML node <parameter>parent</parameter> that is an element with name <parameter>name</parameter> and return the xml Node pointer of it. </para>

504

505

<para>Returns NULL if no such child was found.</para>

506

507

</sect2>

508

</sect1>

509

510

</chapter>

Older »