From a71ca13285f67f081df53cf40a0170a723ebdec3 Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Mon, 19 Feb 2007 17:18:16 +0000 Subject: [PATCH] Header documentation changes. --- lib/silcapputil/silcidcache.h | 2 +- lib/silcclient/silcclient.h | 11 +---- lib/silcclient/silcclient_entry.h | 19 +++++++++ lib/silccore/DIRECTORY | 1 + lib/silccore/silcpacket.h | 10 ++--- lib/silccrypt/silcpk.h | 2 +- lib/silchttp/silchttpphp.h | 4 +- lib/silcske/silcske.h | 4 +- lib/silcskr/silcskr.h | 4 +- lib/silcutil/DIRECTORY | 14 +++---- lib/silcutil/silcatomic.h | 2 +- lib/silcutil/silcbuffmt.h | 6 +-- lib/silcutil/silccond.h | 24 +++++------ lib/silcutil/silcfsm.h | 2 +- lib/silcutil/silcnet.h | 4 +- lib/silcutil/silcsocketstream.h | 4 +- lib/silcutil/silctypes.h | 67 +++++++++++-------------------- 17 files changed, 86 insertions(+), 94 deletions(-) diff --git a/lib/silcapputil/silcidcache.h b/lib/silcapputil/silcidcache.h index 088dd058..05a009de 100644 --- a/lib/silcapputil/silcidcache.h +++ b/lib/silcapputil/silcidcache.h @@ -220,7 +220,7 @@ SilcBool silc_idcache_update(SilcIDCache cache, SilcIDCacheEntry entry, void *new_id, char *new_name, SilcBool free_old_name); -/****f* silcapputil/SilcIDCacheAPI/silc_idcache_update +/****f* silcapputil/SilcIDCacheAPI/silc_idcache_update_by_context * * SYNOPSIS * diff --git a/lib/silcclient/silcclient.h b/lib/silcclient/silcclient.h index 4d3fc3a0..26d7b1d4 100644 --- a/lib/silcclient/silcclient.h +++ b/lib/silcclient/silcclient.h @@ -49,15 +49,6 @@ * employ concurrency control if the callbacks need to access shared data * in the application. Messages are also received in that thread. * - * All entries (SilcClientEntry, SilcChannelEntry and SilcServerEntry) are - * reference counted. If application wishes to save an entry pointer it must - * always first acquire a reference. The reference must be released once the - * entry is not needed anymore. If application wants to read any data from - * the entry structure it must first lock the entry. This protects access to - * the entries in multithreaded environment. If threads are not used, locking - * the entries is not needed. They however still must be referenced even - * when threads are not used. - * ***/ #ifndef SILCCLIENT_H @@ -2008,7 +1999,7 @@ SilcBool silc_client_set_away_message(SilcClient client, * * The SILC_CLIENT_FILE_MONITOR_DISCONNECT will be called if remote * disconnects the session connection. The silc_client_file_close must - * be called when this status is received. The session is over when + * be called when this status is received. The session is over when * this is received. * * The SILC_CLIENLT_FILE_MONITOR_ERROR is called in case some error diff --git a/lib/silcclient/silcclient_entry.h b/lib/silcclient/silcclient_entry.h index aae2c044..6ebe4129 100644 --- a/lib/silcclient/silcclient_entry.h +++ b/lib/silcclient/silcclient_entry.h @@ -17,6 +17,25 @@ */ +/****h* silcclient/Client Library Interface + * + * DESCRIPTION + * + * This header file includes the SilcClientEntry, SilcChannelEntry and + * SilcServer entry structures and various routines to search, resolve and + * handle these structures. + * + * All entries (SilcClientEntry, SilcChannelEntry and SilcServerEntry) are + * reference counted. If application wishes to save an entry pointer it must + * always first acquire a reference. The reference must be released once the + * entry is not needed anymore. If application wants to read any data from + * the entry structure it must first lock the entry. This protects access to + * the entries in multithreaded environment. If threads are not used, locking + * the entries is not needed. They however still must be referenced even + * when threads are not used. + * + ***/ + #ifndef SILCCLIENT_ENTRY_H #define SILCCLIENT_ENTRY_H diff --git a/lib/silccore/DIRECTORY b/lib/silccore/DIRECTORY index 7e0226fe..a924294e 100644 --- a/lib/silccore/DIRECTORY +++ b/lib/silccore/DIRECTORY @@ -12,6 +12,7 @@ @LINK=silcargument.html:SILC Argument Interface @LINK=silcattrs.html:SILC Attributes Interface @LINK=silcpacket.html:Packet Protocol Interface +@LINK=silcpubkey.html:SILC Public Key Payload Interface --> SILC Core Library diff --git a/lib/silccore/silcpacket.h b/lib/silccore/silcpacket.h index cef13ca2..4cc2b442 100644 --- a/lib/silccore/silcpacket.h +++ b/lib/silccore/silcpacket.h @@ -17,7 +17,7 @@ */ -/****h* silccore/Packet Protocol Interface +/****h* silccore/SILC Packet Engine Interface * * DESCRIPTION * @@ -310,11 +310,11 @@ typedef void (*SilcPacketErrorCb)(SilcPacketEngine engine, void *callback_context, void *stream_context); -/****s* silccore/SilcPacketAPI/SilcPacketStream +/****s* silccore/SilcPacketAPI/SilcPacketCallbacks * * NAME * - * typedef struct SilcPacketStreamStruct *SilcPacketStream; + * typedef struct { ... } *SilcPacketCallbacks; * * DESCRIPTION * @@ -695,7 +695,7 @@ SilcStream silc_packet_stream_wrap(SilcPacketStream stream, SilcPacketWrapCoder coder, void *context); -/****f* silccore/SilcPacketAPI/silc_packet_get_sender +/****f* silccore/SilcPacketAPI/silc_packet_stream_is_udp * * SYNOPSIS * @@ -1037,7 +1037,7 @@ SilcBool silc_packet_send_va_ext(SilcPacketStream stream, ***/ void *silc_packet_wait_init(SilcPacketStream stream, ...); -/****f* silccore/SilcPacketAPI/silc_packet_wait +/****f* silccore/SilcPacketAPI/silc_packet_wait_uninit * * SYNOPSIS * diff --git a/lib/silccrypt/silcpk.h b/lib/silccrypt/silcpk.h index 3e1e464c..49b64001 100644 --- a/lib/silccrypt/silcpk.h +++ b/lib/silccrypt/silcpk.h @@ -126,7 +126,7 @@ SilcBool silc_pkcs_silc_generate_key(const char *algorithm, SilcPublicKey *ret_public_key, SilcPrivateKey *ret_private_key); -/****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_decode_identifier +/****f* silccrypt/SilcPubkeyAPI/silc_pkcs_silc_encode_identifier * * SYNOPSIS * diff --git a/lib/silchttp/silchttpphp.h b/lib/silchttp/silchttpphp.h index f0c51122..ce3be142 100644 --- a/lib/silchttp/silchttpphp.h +++ b/lib/silchttp/silchttpphp.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2006 Pekka Riikonen + Copyright (C) 2006 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -46,7 +46,7 @@ ***/ SilcBuffer silc_http_php(char *php_data); -/****f* silchttp/SilcHTTPServer/silc_http_php +/****f* silchttp/SilcHTTPServer/silc_http_php_file * * SYNOPSIS * diff --git a/lib/silcske/silcske.h b/lib/silcske/silcske.h index 8bba8ed0..50ae1d9e 100644 --- a/lib/silcske/silcske.h +++ b/lib/silcske/silcske.h @@ -426,7 +426,7 @@ void silc_ske_set_callbacks(SilcSKE ske, SilcSKECompletionCb completed, void *context); -/****f* silcske/SilcSKEAPI/silc_ske_initiator_start +/****f* silcske/SilcSKEAPI/silc_ske_initiator * * SYNOPSIS * @@ -664,7 +664,7 @@ silc_ske_process_key_material_data(unsigned char *data, ***/ void silc_ske_free_key_material(SilcSKEKeyMaterial key); -/****f* silcske/SilcSKEAPI/silc_ske_free_key_material +/****f* silcske/SilcSKEAPI/silc_ske_free_rekey_material * * SYNOPSIS * diff --git a/lib/silcskr/silcskr.h b/lib/silcskr/silcskr.h index c0ede323..8fe975bd 100644 --- a/lib/silcskr/silcskr.h +++ b/lib/silcskr/silcskr.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2005 Pekka Riikonen + Copyright (C) 2005 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -442,7 +442,7 @@ SilcBool silc_skr_find_set_country(SilcSKRFind find, const char *country); SilcBool silc_skr_find_set_public_key(SilcSKRFind find, SilcPublicKey public_key); -/****f* silcskr/SilcSKRAPI/silc_skr_find_set_public_key +/****f* silcskr/SilcSKRAPI/silc_skr_find_set_context * * SYNOPSIS * diff --git a/lib/silcutil/DIRECTORY b/lib/silcutil/DIRECTORY index 2a566a74..83b11975 100644 --- a/lib/silcutil/DIRECTORY +++ b/lib/silcutil/DIRECTORY @@ -13,9 +13,9 @@ @LINK=silcatomic.html:Atomic Operations Interface @LINK=silcnet.html:Network (TCP and UDP) Interface @LINK=silcschedule.html:Scheduler Interface +@LINK=silcstream.html:Abstract Stream Interface @LINK=silcsocketstream.html:Socket Stream Interface @LINK=silcfdstream.html:File Descriptor Stream Interface -@LINK=silcstream.html:Abstract Stream Interface @LINK=silcfsm.html:Finite State Machine Interface @LINK=silcfileutil.html:File Utility Functions @LINK=silcstrutil.html:String Utility Interface @@ -41,12 +41,12 @@ Introduction

-SILC Utility Library provides various utility routines for the applications. -For example, it provides the application's main loop, called the SILC -Scheduler. It can handle all kinds of tasks, like socket connections and -timeout tasks. The SILC Utility Library also provides various buffer -management routines. All of these routines work on multiple platforms -such as Unix and WIN32. +SILC Utility Library provides a full featured runtime library for +applications. It provides the application's main loop, called SILC +Scheduler, threads, locks, file utilities, file streams, socket streams, +TCP and UDP network routines, a finite state machine, lists, a hash table, +UTF-8 routines and other string utilities, and many other utility routines. +The library works on multiple platforms.

@LINKS@ diff --git a/lib/silcutil/silcatomic.h b/lib/silcutil/silcatomic.h index e2719b4c..15b39319 100644 --- a/lib/silcutil/silcatomic.h +++ b/lib/silcutil/silcatomic.h @@ -680,7 +680,7 @@ void *silc_atomic_get_pointer(SilcAtomicPointer *atomic) * ***/ -/****f* silcutil/SilcAtomicAPI/silc_atomic_add_int32 +/****f* silcutil/SilcAtomicAPI/silc_atomic_add_int16 * * SYNOPSIS * diff --git a/lib/silcutil/silcbuffmt.h b/lib/silcutil/silcbuffmt.h index 2c7b1d64..909d6ead 100644 --- a/lib/silcutil/silcbuffmt.h +++ b/lib/silcutil/silcbuffmt.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1997 - 2006 Pekka Riikonen + Copyright (C) 1997 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -253,11 +253,11 @@ int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...); ***/ int silc_buffer_format_vp(SilcBuffer dst, va_list ap); -/****f* silcutil/SilcBufferFormatAPI/silc_buffer_format_vp +/****f* silcutil/SilcBufferFormatAPI/silc_buffer_sformat_vp * * SYNOPSIS * - * int silc_buffer_format_vp(SilcBuffer dst, va_list vp); + * int silc_buffer_sformat_vp(SilcStack stack, SilcBuffer dst, va_list vp); * * DESCRIPTION * diff --git a/lib/silcutil/silccond.h b/lib/silcutil/silccond.h index 25f7c92c..1fe8bb21 100644 --- a/lib/silcutil/silccond.h +++ b/lib/silcutil/silccond.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2006 Pekka Riikonen + Copyright (C) 2006 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -17,12 +17,12 @@ */ -/****h* silcutil/SILC Conditional Variable Interface +/****h* silcutil/SILC Condition Variable Interface * * DESCRIPTION * - * A conditional variable interface for multi-thread synchronization. - * Conditional variables enable threads to suspend execution and yield + * A condition variable interface for multi-thread synchronization. + * Condition variables enable threads to suspend execution and yield * the processors until some predicate on some shared data is satisfied. * ***/ @@ -38,7 +38,7 @@ * * DESCRIPTION * - * This context is the actual conditional variable and is allocated + * This context is the actual condition variable and is allocated * by silc_cond_alloc and given as argument to all silc_cond_* * functions. It is freed by the silc_cond_free function. * @@ -53,10 +53,10 @@ typedef struct SilcCondStruct *SilcCond; * * DESCRIPTION * - * Allocates SILC Conditional variable context. The conditional must + * Allocates SILC Condition variable context. The condition must * be allocated before it can be used. It is freed by the * silc_cond_free function. This returns TRUE and allocated - * conditional in to the `cond' pointer and FALSE on error. + * condition in to the `cond' pointer and FALSE on error. * ***/ SilcBool silc_cond_alloc(SilcCond *cond); @@ -69,7 +69,7 @@ SilcBool silc_cond_alloc(SilcCond *cond); * * DESCRIPTION * - * Free conditional variable context. If `cond' is NULL this function + * Free condition variable context. If `cond' is NULL this function * has no effect. * ***/ @@ -83,8 +83,8 @@ void silc_cond_free(SilcCond cond); * * DESCRIPTION * - * Waits for conditional variable `cond' to be signalled. This function - * will block the calling thread until the conditional variable is + * Waits for condition variable `cond' to be signalled. This function + * will block the calling thread until the condition variable is * signalled. The `mutex' must be locked before calling this function. * The `mutex' will be unlocked inside this function. After this * function returns the `mutex' is in locked state again. @@ -108,11 +108,11 @@ void silc_cond_wait(SilcCond cond, SilcMutex mutex); * * DESCRIPTION * - * Waits for conditional variable `cond' to be signalled or for the + * Waits for condition variable `cond' to be signalled or for the * `timeout' to expire. The timeout is in milliseconds. If it is 0 * no timeout exist. Returns FALSE if timeout expired, TRUE when * signalled. This function will block the calling thread until the - * conditional variable is signalled. The `mutex' must be locked before + * condition variable is signalled. The `mutex' must be locked before * calling this function. The `mutex' will be unlocked inside this * function. After this function returns the `mutex' is in locked * state again. diff --git a/lib/silcutil/silcfsm.h b/lib/silcutil/silcfsm.h index 0eb53f4e..b23e36ef 100644 --- a/lib/silcutil/silcfsm.h +++ b/lib/silcutil/silcfsm.h @@ -94,7 +94,7 @@ typedef struct SilcFSMObject SilcFSMStruct; ***/ typedef struct SilcFSMObject *SilcFSMThread; -/****s* silcutil/SilcFSMAPI/SilcFSM +/****s* silcutil/SilcFSMAPI/SilcFSMThreadStruct * * NAME * diff --git a/lib/silcutil/silcnet.h b/lib/silcutil/silcnet.h index c4a1f045..b2adca76 100644 --- a/lib/silcutil/silcnet.h +++ b/lib/silcutil/silcnet.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 1997 - 2006 Pekka Riikonen + Copyright (C) 1997 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -196,7 +196,7 @@ void silc_net_close_listener(SilcNetListener listener); * using silc_async_abort the `callback' will not be called. If NULL * is returned the operation cannot be aborted. * - */ + ***/ SilcAsyncOperation silc_net_tcp_connect(const char *local_ip_addr, const char *remote_ip_addr, int remote_port, diff --git a/lib/silcutil/silcsocketstream.h b/lib/silcutil/silcsocketstream.h index 560e7e0f..4d4acec7 100644 --- a/lib/silcutil/silcsocketstream.h +++ b/lib/silcutil/silcsocketstream.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2005 - 2006 Pekka Riikonen + Copyright (C) 2005 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -158,7 +158,7 @@ SilcStream silc_socket_udp_stream_create(SilcSocket sock, SilcBool connected, SilcSchedule schedule); -/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_get_info +/****f* silcutil/SilcSocketStreamAPI/silc_socket_stream_is_udp * * SYNOPSIS * diff --git a/lib/silcutil/silctypes.h b/lib/silcutil/silctypes.h index 7500b1fb..f1f8ddb1 100644 --- a/lib/silcutil/silctypes.h +++ b/lib/silcutil/silctypes.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2002 - 2006 Pekka Riikonen + Copyright (C) 2002 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -31,6 +31,29 @@ #ifndef SILCTYPES_H #define SILCTYPES_H +/****d* silcutil/SILCTypes/SilcBool + * + * NAME + * + * typedef unigned char SilcBool; + * + * DESCRIPTION + * + * Boolean value, and is always 8-bits. Represents value 0 or 1. + * + ***/ +typedef unsigned char SilcBool; + +/* The bool macro is deprecated. Use SilcBool instead. */ +#ifdef SILC_MACOSX +#define bool _Bool +#endif +#ifndef __cplusplus +#ifndef bool +#define bool unsigned char +#endif +#endif + /****d* silcutil/SILCTypes/TRUE * * NAME @@ -65,48 +88,6 @@ #endif /***/ -/****d* silcutil/SILCTypes/SilcBool - * - * NAME - * - * typedef unigned char SilcBool; - * - * DESCRIPTION - * - * Boolean value, and is always 8-bits. Represents value 0 or 1. - * - ***/ -typedef unsigned char SilcBool; - -/****d* silcutil/SILCTypes/bool - * - * NAME - * - * #define SilcBool ... - * - * DESCRIPTION - * - * Boolean value, and is 8-bits. Represents value 0 or 1. In - * C++ code this type is defined by the C++, and this definition is - * not used. - * - * NOTES - * - * This macro is deprecated. Use SilcBool instead. - * - * SOURCE - */ -#ifdef SILC_MACOSX -#define bool _Bool -#endif - -#ifndef __cplusplus -#ifndef bool -#define bool unsigned char -#endif -#endif -/***/ - /* Our offsetof macro */ #define silc_offsetof(TYPE, MEMBER) ((size_t) &((TYPE *)0)->MEMBER) -- 2.24.0