services.h 14 KB
Newer Older
Linus Tolke's avatar
Linus Tolke committed
1
/*
2
 * $Id: services.h,v 0.52 2001/12/28 19:05:00 ceder Exp $
Per Cederqvist's avatar
Per Cederqvist committed
3
 * Copyright (C) 1991-1999, 2001  Lysator Academic Computer Association.
Linus Tolke's avatar
Linus Tolke committed
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 *
 * This file is part of the LysKOM server.
 * 
 * LysKOM is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by 
 * the Free Software Foundation; either version 1, or (at your option) 
 * any later version.
 * 
 * LysKOM is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with LysKOM; see the file COPYING.  If not, write to
 * Lysator, c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN,
 * or the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, 
 * MA 02139, USA.
 *
 * Please mail bug reports to bug-lyskom@lysator.liu.se. 
 */
Per Cederqvist's avatar
.  
Per Cederqvist committed
25
26
27
28
/*
 *  services.h  --  All the services the LysKOM server makes available
 *		    for clients.
 *
29
30
 *  These functions match the requests defined in doc/Protocol-A.texi.
 *  See the descriptions in that file for documentation.
Per Cederqvist's avatar
.  
Per Cederqvist committed
31
32
33
34
35
 *
 *  Created by ceder 1990-03-23
 */


36
37
#ifndef  SERVICES_H_ALREADY_INCLUDED
#define  SERVICES_H_ALREADY_INCLUDED
Per Cederqvist's avatar
.  
Per Cederqvist committed
38
39
40
41
42
43
44



/*
 * Session control
 */

45
extern  Success
46
47
login_old (Pers_no	person,
	   const String	passwd);
48

Per Cederqvist's avatar
.  
Per Cederqvist committed
49
extern  Success
50
51
52
login (Pers_no		person,
       const String	passwd,
       Bool		invisible);
Per Cederqvist's avatar
.  
Per Cederqvist committed
53
54

extern  Success
55
logout (void);	/* can never fail */
Per Cederqvist's avatar
.  
Per Cederqvist committed
56
57
58

/* Change Conference */
extern  Success
59
change_conference (Conf_no conference);
Per Cederqvist's avatar
.  
Per Cederqvist committed
60
61
62
63


/* Change name of a person or conference. */
extern  Success
64
65
change_name (Conf_no	  conf_no,
	     const String new_name);
Per Cederqvist's avatar
.  
Per Cederqvist committed
66
67

extern  Success
68
change_what_i_am_doing (String  what_am_i_doing);
Per Cederqvist's avatar
.  
Per Cederqvist committed
69

70
71
/* Client version: one call to set, two to retrieve. */
extern  Success
72
73
set_client_version (const String client_name,
		    const String client_version);
74
75

extern  Success
76
77
get_client_name (Session_no session_no,
		 String *result);
78
79

extern  Success
80
81
get_client_version (Session_no session_no,
		    String *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
82
83
84
85

/* Get info about a session */

extern  Success
86
87
get_session_info  (Session_no session_no,
		   Session_info *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
88

89
extern  Success
90
91
get_session_info_ident  (Session_no session_no,
			 Session_info_ident *result);
92

Per Cederqvist's avatar
Per Cederqvist committed
93
extern  Success
94
95
get_static_session_info (Session_no session_no,
			 Static_session_info *result);
Per Cederqvist's avatar
Per Cederqvist committed
96

Per Cederqvist's avatar
.  
Per Cederqvist committed
97
98
99
100
101
102
/*
 * Disconnect a session. You can disconnect your own session (even if
 * you are not logged in) and any session where you are supervisor of
 * the user that is logged in on that session.
 */
extern  Success
103
disconnect (Session_no session_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
104
105
106
107
108

/*
 * Returns your session number
 */
extern  Success
109
who_am_i (Session_no *session_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
110

Per Cederqvist's avatar
Per Cederqvist committed
111
112
113
114
115
/*
 * Set state in the session
 */

extern  Success
116
user_active (void);
Per Cederqvist's avatar
.  
Per Cederqvist committed
117
118
119
120
121
122
123
124
125

/******************************
*     Person-related calls    *
******************************/

/*
 *  Create a new person.  Returns 0 if any error occured.
 */
extern  Pers_no
126
127
create_person_old (const String  name,
		   const String  passwd);
128
129

extern Pers_no
130
131
132
133
create_person (const String name,
	       const String passwd,
	       Personal_flags flags,
	       Aux_item_list *conf_aux);
Per Cederqvist's avatar
.  
Per Cederqvist committed
134
135


David Byers's avatar
David Byers committed
136
137
138
139
extern Success
set_pers_flags(Pers_no pers_no,
               Personal_flags flags);

Per Cederqvist's avatar
.  
Per Cederqvist committed
140
141
/* Obsolete call; use get_person_stat instead. */
extern  Success
142
143
144
get_person_stat_old (Pers_no		  person,
		     int		  mask,
		     Person		* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
145
146

extern  Success
147
148
get_person_stat (Pers_no	  person,
		 Person		* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
149
150

extern  Success
151
152
153
154
get_created_texts (Pers_no		  person,
		   Local_text_no	  first,
		   unsigned long	  no_of_texts,
		   L2g_iterator 	 *created_texts);
Per Cederqvist's avatar
.  
Per Cederqvist committed
155

156
extern  Success
157
158
159
160
map_created_texts (Pers_no	  person,
		   Local_text_no  first,
		   unsigned long  no_of_texts,
		   Text_mapping  *created_texts);
161

162
extern  Success
163
164
165
166
167
get_membership_old (Pers_no		  person,
		    unsigned short	  first,
		    unsigned short	  no_of_confs,
		    Bool		  want_read_texts,
		    Membership_list	* memberships);
168

Per Cederqvist's avatar
.  
Per Cederqvist committed
169
extern  Success
170
171
172
173
174
get_membership (Pers_no		  person,
		unsigned short	  first,
		unsigned short	  no_of_confs,
		Bool		  want_read_texts,
		Membership_list	* memberships);
Per Cederqvist's avatar
.  
Per Cederqvist committed
175
176

extern  Success
177
178
set_priv_bits (Pers_no	 person,
	       Priv_bits privileges);
Per Cederqvist's avatar
.  
Per Cederqvist committed
179
180
181
182
183
184


/*  Set the password of PERSON to NEW_PWD.  OLD_PWD is the password
 *  of the person who does the set.  This is not necessarily the
 *  same as the one who gets it set.	*/
extern  Success
185
186
187
set_passwd (Pers_no	   person,
	    const String   old_pwd,
	    const String   new_pwd);
Per Cederqvist's avatar
.  
Per Cederqvist committed
188
189
190


/* You can query for unread texts without logging in. */
191
extern  Success
192
193
194
query_read_texts_old (Pers_no	     pers_no,
		      Conf_no	     conf_no,
		      Membership   * result  );
195

Per Cederqvist's avatar
.  
Per Cederqvist committed
196
extern  Success
197
198
199
query_read_texts (Pers_no      pers_no,
		  Conf_no      conf_no,
		  Membership * result  );
Per Cederqvist's avatar
.  
Per Cederqvist committed
200
201
202


extern Success
203
204
get_unread_confs(Pers_no       pers_no,
		 Conf_no_list *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
205
206

extern Success
207
208
set_user_area(Pers_no	pers_no,
	      Text_no	user_area);
Per Cederqvist's avatar
.  
Per Cederqvist committed
209
210
211
212
213
214
215
216


/****************************************
*	Conference-related calls	*
****************************************/


extern  Conf_no
217
218
create_conf_old (const String	  name,
		 Conf_type	  type);
219
220

extern Conf_no
221
222
223
create_conf (const String name,
	     Conf_type type,
	     Aux_item_list *aux);
224
225

extern Success
226
227
228
modify_conf_info (Conf_no conf_no,
		  Number_list *items_to_delete,
		  Aux_item_list *items_to_add);
Per Cederqvist's avatar
.  
Per Cederqvist committed
229
230
231
232


/*  Delete a conference.  Also used to delete persons.  */
extern  Success
233
delete_conf (Conf_no	conf);
Per Cederqvist's avatar
.  
Per Cederqvist committed
234
235
236
237
238


/*
 *  Map conference name to number.  Returns a list of the conferences
 *  that match the name NAME. Can be done without logging in.
239
 * This should be phased out.
Per Cederqvist's avatar
.  
Per Cederqvist committed
240
241
 */
extern  Success
242
243
lookup_name (const String   name,
	     Conf_list_old *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
244

245
extern Success
246
247
248
249
lookup_z_name (const String name,
	       int want_persons,
	       int want_confs,
	       Conf_z_info_list *result);
250

251
252
/* Use these two lookup-calls instead of lookup_name */
extern  Success
253
254
lookup_person (const String  pattern,
	       Conf_no_list  *result);
255
256

extern  Success
257
258
lookup_conf (const String  pattern,
	     Conf_no_list  *result);
259

260
261
/* Two functions for matching regexps. */
extern  Success
262
263
re_lookup_person (const String  regexp,
		  Conf_no_list  *result);
264
265

extern  Success
266
267
re_lookup_conf (const String  regexp,
		Conf_no_list  *result);
268

269
extern  Success
270
271
272
273
re_z_lookup (const String      regexp,
	     int               want_persons,
	     int	       want_confs,
	     Conf_z_info_list *result);
274

275
extern Success
276
get_collate_table (String * result);
277
278

extern  Success
279
280
281
get_conf_stat_older (Conf_no	 conf_no,
		     int	 mask,
		     Conference *result);
282

Per Cederqvist's avatar
.  
Per Cederqvist committed
283
extern  Success
284
285
get_conf_stat_old (Conf_no		  conf_no,
		   Conference		* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
286
287

extern  Success
288
289
get_conf_stat (Conf_no		  conf_no,
	       Conference	* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
290

291
extern Success
292
293
get_uconf_stat (Conf_no		  conf_no,
		Small_conf	* result);
294

Per Cederqvist's avatar
.  
Per Cederqvist committed
295
extern  Success
296
297
298
299
get_members (Conf_no	      conf,
	     unsigned short   first,
	     unsigned short   no_of_members,
	     Member_list    * members);
300
301

extern  Success
302
303
304
305
get_members_old (Conf_no	  conf,
		 unsigned short   first,
		 unsigned short   no_of_members,
		 Member_list	* members	);
Per Cederqvist's avatar
.  
Per Cederqvist committed
306
307
308
309
310



/* add_member is also used to change the priority of a conference */
extern  Success
311
312
313
314
315
add_member (Conf_no		conf_no,
	    Pers_no		pers_no,
	    unsigned char	priority,
	    unsigned short	where, /* Range of where is [0..] */
	    Membership_type   * type);
316
317

extern  Success
318
319
320
321
add_member_old (Conf_no		conf_no,
		Pers_no		pers_no,
		unsigned char	priority,
		unsigned short	where	); /* Range of where is [0..] */
322
323

extern Success
324
325
326
set_membership_type (Pers_no          pers_no,
		     Conf_no          conf_no,
		     Membership_type *type   );
Per Cederqvist's avatar
.  
Per Cederqvist committed
327
328
329


extern  Success
330
331
sub_member (Conf_no	conf_no,
	    Pers_no	pers_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
332
333
334
335
336


/*
 * Tell the server that I want to mark/unmark texts as read so that I
 * get no_of_unread unread texts in conf_no.
Kent Engström's avatar
Kent Engström committed
337
338
339
 *
 * The new alternative function marks last_read as the last read local
 * text. Use this one to avoid race conditions.
Per Cederqvist's avatar
.  
Per Cederqvist committed
340
 */
Kent Engström's avatar
Kent Engström committed
341

Per Cederqvist's avatar
.  
Per Cederqvist committed
342
extern  Success
343
344
set_unread (Conf_no   conf_no,
	    Text_no   no_of_unread);
Per Cederqvist's avatar
.  
Per Cederqvist committed
345

Kent Engström's avatar
Kent Engström committed
346
extern  Success
347
348
set_last_read (Conf_no       conf_no,
	       Local_text_no last_read);
Kent Engström's avatar
Kent Engström committed
349
350


Per Cederqvist's avatar
.  
Per Cederqvist committed
351
352
353
354
355
356
/*
 * set_presentation and set_etc_motd also does some magic with the
 * no_of_marks field in the Text_stat structure of the old and new text.
 */ 

extern  Success
357
358
set_presentation (Conf_no   conf_no,
		  Text_no   text_no); /* 0 to delete pres. */
Per Cederqvist's avatar
.  
Per Cederqvist committed
359
360

extern  Success
361
362
set_etc_motd (Conf_no	  conf_no,
	      Text_no	  text_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
363
364
365


extern  Success
366
367
set_supervisor (Conf_no	  conf_no,
		Conf_no	  admin	);
Per Cederqvist's avatar
.  
Per Cederqvist committed
368
369

extern  Success
370
371
set_permitted_submitters (Conf_no	  conf_no,
			  Conf_no	  perm_sub);
Per Cederqvist's avatar
.  
Per Cederqvist committed
372
373

extern  Success
374
375
set_super_conf (Conf_no	  conf_no,
		Conf_no	  super_conf);
Per Cederqvist's avatar
.  
Per Cederqvist committed
376
377

extern  Success
378
379
set_conf_type (Conf_no	  conf_no,
	       Conf_type  type	);
Per Cederqvist's avatar
.  
Per Cederqvist committed
380
extern  Success
381
382
set_garb_nice (Conf_no	  conf_no,
	       Garb_nice  days); /* number of days */
Per Cederqvist's avatar
.  
Per Cederqvist committed
383

384
extern  Success
385
386
set_expire (Conf_no	  conf_no,
	    Garb_nice	  expire); /* number of days */
387

Per Cederqvist's avatar
.  
Per Cederqvist committed
388

389
extern Success
390
391
set_keep_commented(Conf_no	conf_no,
                   Garb_nice	keep_commented);	/* number of days */
392
393


Per Cederqvist's avatar
.  
Per Cederqvist committed
394
395
396
397
398
399
400

/********************************
*     Calls to handle marks     *
********************************/


extern  Success
401
get_marks (Mark_list *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
402
403
404
405
406
407



/*
 *  Will fail if the user is not allowed to read the text.
 */
408
409
/* This function uses mark_type==0 to delete the mark. */
extern  Success
410
411
mark_text_old (Text_no	  	  text,
	       unsigned char	  mark_type);
412

413
414

/* Using this function, you can set mark_type==0. */
Per Cederqvist's avatar
.  
Per Cederqvist committed
415
extern  Success
416
417
mark_text (Text_no	  text,
	   unsigned char  mark_type);
418

Per Cederqvist's avatar
.  
Per Cederqvist committed
419

420
421
/* Remove a mark, reporting an error if you had not marked the text. */
extern  Success
422
unmark_text (Text_no	  text);
423

Per Cederqvist's avatar
.  
Per Cederqvist committed
424
425
426
427
428
429
430
431
432



/*******************************
*     Calls to handle texts    *
*******************************/


extern  Success
433
434
435
436
get_text (Text_no	  text,
	  String_size	  start_char,
	  String_size	  end_char,
	  String	* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
437
438
439


extern  Success
440
441
get_text_stat (Text_no    text,
	       Text_stat *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
442

443
extern  Success
444
445
get_text_stat_old (Text_no    text,
		   Text_stat *result);
446

Per Cederqvist's avatar
.  
Per Cederqvist committed
447
extern  Success
448
449
450
mark_as_read (Conf_no		    conference,
	      int		    no_of_texts,
	      const Local_text_no * text_arr  );
Per Cederqvist's avatar
.  
Per Cederqvist committed
451
452
453
454


/* Returns 0 on error */
extern  Text_no
455
456
457
create_text (const String     message,
	     Misc_info_list * misc,
	     Aux_item_list  * aux);
458
459

extern Text_no
460
461
create_text_old (const String     message,
		 Misc_info_list	* misc	    );
Per Cederqvist's avatar
.  
Per Cederqvist committed
462

463
/* Returns 0 on error.  */
464
extern  Text_no
465
466
467
create_anonymous_text (const String      message,
		       Misc_info_list  * misc,
		       Aux_item_list    *aux);
468
469

extern  Text_no
470
471
create_anonymous_text_old (const String      message,
			   Misc_info_list  * misc);
472

Per Cederqvist's avatar
.  
Per Cederqvist committed
473
extern Success
474
delete_text( Text_no text_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
475

476
extern Success
477
478
479
modify_text_info(Text_no        text,
		 Number_list   *items_to_delete, 
		 Aux_item_list *aux);
Per Cederqvist's avatar
.  
Per Cederqvist committed
480
481
482


extern  Success
483
484
485
add_recipient (Text_no	      text_no,
	       Conf_no	      conf_no,
	       enum info_type type);
Per Cederqvist's avatar
.  
Per Cederqvist committed
486
487

extern  Success
488
489
sub_recipient (Text_no	  text_no,
	       Conf_no	  conf_no);
Per Cederqvist's avatar
.  
Per Cederqvist committed
490
491
492


extern  Success
493
494
add_comment (Text_no	  comment,
	     Text_no 	  comment_to);
Per Cederqvist's avatar
.  
Per Cederqvist committed
495
496
497
498
499
500


/*
 *  Make the text COMMENT to not be a comment to text COMMENT_TO
 */
extern  Success
501
502
sub_comment (Text_no	  comment,
	     Text_no	  comment_to);
Per Cederqvist's avatar
.  
Per Cederqvist committed
503
504

extern Success
505
506
add_footnote (Text_no	footnote,
	      Text_no 	footnote_to);
Per Cederqvist's avatar
.  
Per Cederqvist committed
507
508

extern Success
509
510
sub_footnote (Text_no	footnote,
	      Text_no	parent);
Per Cederqvist's avatar
.  
Per Cederqvist committed
511
512

extern  Success
513
514
515
516
get_map (Conf_no	  conf_no,
	 Local_text_no	  first_local_no,
	 unsigned long	  no_of_texts,
	 L2g_iterator    *result);
517
518

extern Success
519
520
521
522
local_to_global (Conf_no       conf_No,
		 Local_text_no first_local_no,
		 unsigned long no_of_texts,
		 Text_mapping *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
523
524
525
526
527
528
529


/*
 *  Ask what the server thinks the time is. This
 *  might differ if on two different machines.
 */
extern  Success
530
get_time (time_t *t);
Per Cederqvist's avatar
.  
Per Cederqvist committed
531
532


Linus Tolke's avatar
Linus Tolke committed
533
534
535
/*
 *  Gets the last text before a given time.
 */
536

537
extern  Success
538
get_last_text (struct tm *clk, Text_no *result);
Linus Tolke's avatar
Linus Tolke committed
539

540
541
542
543
544
/*
 * Return next/previous existing text-no.
 */

extern  Success
545
find_next_text_no (Text_no start, Text_no *result);
546
547

extern  Success
548
find_previous_text_no (Text_no start, Text_no *result);
549
550


Per Cederqvist's avatar
.  
Per Cederqvist committed
551
552
553
554
/*
 * Who is logged on now?
 */
extern  Success
555
who_is_on_old (Who_info_list_old	* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
556
557

extern  Success
558
who_is_on (Who_info_list	* result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
559

560
extern  Success
561
who_is_on_ident (Who_info_ident_list *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
562

Per Cederqvist's avatar
Per Cederqvist committed
563
extern  Success
564
565
566
567
who_is_on_dynamic (int want_visible,
		   int want_invisible,
		   long active_last,
		   Dynamic_session_info_list *result);
Per Cederqvist's avatar
Per Cederqvist committed
568

Per Cederqvist's avatar
.  
Per Cederqvist committed
569
570
571
/*
 *  Return various information about the server
 */
572
extern  Success
573
get_info_old (Info *result);
574

Per Cederqvist's avatar
.  
Per Cederqvist committed
575
extern  Success
576
get_info (Info *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
577

578
extern  Success
579
get_version_info (Version_info *result);
580

Per Cederqvist's avatar
.  
Per Cederqvist committed
581
582
583
584
585

/*
 * Privileged calls.
 */

David Byers's avatar
David Byers committed
586
extern Success
587
set_info(Info *info);
David Byers's avatar
David Byers committed
588

589
extern Success
590
modify_system_info(Number_list      *items_to_delete,
591
		   Aux_item_list    *items_to_add);
592

Per Cederqvist's avatar
.  
Per Cederqvist committed
593
extern Success
594
set_motd_of_lyskom (Text_no motd);
Per Cederqvist's avatar
.  
Per Cederqvist committed
595
596
597
598
599

/*
 * Set ena_level. 0 means don't use any privileges.
 */
extern Success
600
enable (unsigned char ena_level);
Per Cederqvist's avatar
.  
Per Cederqvist committed
601
602
603
604
605

/*
 * Make LysKOM sync its files.
 */
extern Success
606
sync_kom (void);
Per Cederqvist's avatar
.  
Per Cederqvist committed
607
608
609
610
611

/*
 * Close LysKOM.
 */
extern Success
612
shutdown_kom (int exit_val);
Per Cederqvist's avatar
.  
Per Cederqvist committed
613
614

/*
615
616
 * Send a message to all clients. This is obsoleted by send_message(),
 * but will remain for compatibility reasons.
Per Cederqvist's avatar
.  
Per Cederqvist committed
617
618
 */
extern Success
619
broadcast (const String message);
Per Cederqvist's avatar
.  
Per Cederqvist committed
620
621
622
623
624
625

/*
 * Send a message to a person, or all persons. If recipient == 0 all
 * connections will receive the message.
 */
extern Success
626
627
send_message (Conf_no recipient,
	      const String message);
Per Cederqvist's avatar
.  
Per Cederqvist committed
628

629
630
631
632
633
/*
 * Selection of asynchronous messages
 */

extern Success
634
accept_async(Number_list *accept_list);
635
636

extern Success
637
query_async(Number_list *result);
Per Cederqvist's avatar
.  
Per Cederqvist committed
638

639
640
641
642
643
/*
 * Aux-items
 */

extern Success
644
query_predefined_aux_items(Number_list *result);
645
646


647
648
#ifdef DEBUG_CALLS
extern Success
649
get_memory_info(Memory_info *result);
650
651

extern Success
652
set_marks(Text_no text_no, unsigned long no_of_marks);
653
654

extern Success
655
656
backdate_text(Text_no text_no,
	      unsigned long seconds);
657

Per Cederqvist's avatar
Per Cederqvist committed
658
659
660
extern Success
start_garb(void);

661
#endif
Per Cederqvist's avatar
.  
Per Cederqvist committed
662
663
    
#endif	/*  _SERVICES_H_ALREADY_INCLUDED__  */