Changeset 185

Show
Ignore:
Timestamp:
08/29/07 22:05:15 (15 months ago)
Author:
zany
Message:

adding doxygen

Location:
trunk
Files:
3 added
3 removed
14 modified

Legend:

Unmodified
Added
Removed

  • trunk/Makefile.am

    r182 r185  
    44                                obexftp.spec \ 
    55                                includes/common.h \ 
     6                                Doxyfile \ 
     7                                Doxyfile.developer \ 
     8                                Doxyfile.coverpage \ 
    69                                config.rpath \ 
    7                                 tcl.m4 
     10                                tcl.m4  
    811 
    912# no uninstall for perl -- ignore it 

  • trunk/bfb/bfb.c

    r156 r185  
    1 /* 
    2  *  bfb/bfb.c: BFB transport encapsulation (used for Siemens mobile equipment) 
     1/** 
     2 *  \file bfb/bfb.c 
     3 *  BFB transport encapsulation (used for Siemens mobile equipment). 
     4 *  ObexFTP library - language bindings for OBEX file transfer. 
    35 * 
    4  *  Copyright (c) 2002 Christian W. Zuckschwerdt <zany@triq.net> 
     6 *  Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    57 * 
    68 *  This program is free software; you can redistribute it and/or modify it 
    … …  
    1921 *      
    2022 */ 
    21 /* 
    22  *  v0.1:  Die,  5 Feb 2002 22:46:19 +0100 
    23  *  v0.4:  Don, 25 Jul 2002 03:16:41 +0200 
    24  */ 
    2523 
    2624#ifdef HAVE_CONFIG_H 
    … …  
    8785#endif 
    8886 
    89 /* returns the whole buffer folded with xor. */ 
     87 
     88/** 
     89        Returns the whole buffer folded with xor. 
     90 */ 
    9091uint8_t bfb_checksum(uint8_t *data, int len) 
    9192{ 
    … …  
    99100} 
    100101 
    101 /* stuff data frame into serial cable encapsulation */ 
    102 /* buffer needs to be of at leaset len+7 size */ 
    103 /* Type 0x01: "prepare" command. */ 
    104 /* Type 0x02: first transmission in a row. */ 
    105 /* Type 0x03: continued transmission. */ 
    106 /* seq needs to be incremented afterwards. */ 
     102 
     103/** 
     104        Stuff data frame into serial cable encapsulation. 
     105        buffer needs to be of at leaset len+7 size 
     106        Type 0x01: "prepare" command. 
     107        Type 0x02: first transmission in a row. 
     108        Type 0x03: continued transmission. 
     109        seq needs to be incremented afterwards. 
     110 */ 
    107111int bfb_stuff_data(uint8_t *buffer, uint8_t type, uint8_t *data, uint16_t len, uint8_t seq) 
    108112{ 
    … …  
    154158} 
    155159 
    156 /* send a cmd, subcmd packet, add chk (no parameters) */ 
     160 
     161/** 
     162        Send a cmd, subcmd packet, add chk (no parameters). 
     163 */ 
    157164int bfb_write_subcmd(fd_t fd, uint8_t type, uint8_t subtype) 
    158165{ 
    … …  
    165172} 
    166173 
    167 /* send a cmd, subcmd packet */ 
     174 
     175/** 
     176        Send a cmd, subcmd packet. 
     177 */ 
    168178int bfb_write_subcmd0(fd_t fd, uint8_t type, uint8_t subtype) 
    169179{ 
    … …  
    171181} 
    172182 
    173 /* send a cmd, subcmd, data packet */ 
     183 
     184/** 
     185        Send a cmd, subcmd, data packet. 
     186 */ 
    174187int bfb_write_subcmd8(fd_t fd, uint8_t type, uint8_t subtype, uint8_t p1) 
    175188{ 
    … …  
    182195} 
    183196 
    184 /* send a cmd, subcmd packet, add chk (one word parameter) */ 
     197 
     198/** 
     199        Send a cmd, subcmd packet, add chk (one word parameter). 
     200 */ 
    185201int bfb_write_subcmd1(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1) 
    186202{ 
    … …  
    200216} 
    201217 
    202 /* send a cmd, subcmd packet, add chk (two word parameter) */ 
     218 
     219/** 
     220        Send a cmd, subcmd packet, add chk (two word parameter). 
     221 */ 
    203222int bfb_write_subcmd2(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1, uint16_t p2) 
    204223{ 
    … …  
    222241} 
    223242 
    224 /* send a cmd, subcmd packet, add chk (three word parameter) */ 
     243 
     244/** 
     245        Send a cmd, subcmd packet, add chk (three word parameter). 
     246 */ 
    225247int bfb_write_subcmd3(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1, uint16_t p2, uint16_t p3) 
    226248{ 
    … …  
    247269} 
    248270 
    249 /* send a cmd, subcmd packet, add long, word parameter */ 
     271 
     272/** 
     273        Send a cmd, subcmd packet, add long, word parameter. 
     274 */ 
    250275int bfb_write_subcmd_lw(fd_t fd, uint8_t type, uint8_t subtype, uint32_t p1, uint16_t p2) 
    251276{ 
    … …  
    272297 
    273298 
    274 /* send actual packets */ 
    275 /* patch from Jorge Ventura to handle EAGAIN from write */ 
     299/** 
     300        Send actual packets. 
     301        Patch from Jorge Ventura to handle EAGAIN from write. 
     302 */ 
    276303int bfb_write_packets(fd_t fd, uint8_t type, uint8_t *buffer, int length) 
    277304{ 
    … …  
    348375} 
    349376 
     377 
     378/** 
     379        Stuff data into packet buffers and send all packets. 
     380 */ 
    350381int bfb_send_data(fd_t fd, uint8_t type, uint8_t *data, uint16_t length, uint8_t seq) 
    351382{ 
    … …  
    369400 
    370401 
    371 /* retrieve actual packets */ 
     402/** 
     403        Retrieve actual packets. 
     404 */ 
    372405/*@null@*/ 
    373406bfb_frame_t *bfb_read_packets(uint8_t *buffer, int *length) 
    … …  
    423456} 
    424457 
     458 
     459/** 
     460        Append BFB frame to a data buffer. 
     461 */ 
    425462int     bfb_assemble_data(bfb_data_t **data, int *size, int *len, bfb_frame_t *frame) 
    426463{ 
    … …  
    459496} 
    460497 
     498 
     499/** 
     500        Check if data buffer is complete and valid. 
     501 */ 
    461502int bfb_check_data(bfb_data_t *data, int len) 
    462503{ 

  • trunk/bfb/bfb.h

    r183 r185  
    1 /* 
    2  *  bfb/bfb.h 
     1/** 
     2 *  \file bfb/bfb.h 
     3 *  BFB transport encapsulation (used for Siemens mobile equipment). 
     4 *  ObexFTP library - language bindings for OBEX file transfer. 
    35 * 
    4  *  Copyright (c) 2002 Christian W. Zuckschwerdt <zany@triq.net> 
     6 *  Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    57 *  
    68 *  This program is free software; you can redistribute it and/or modify it 
    … …  
    3537typedef int fd_t; 
    3638#endif 
    37  
    38 #define BFB_LOG_DOMAIN  "bfb" 
    3939 
    4040#pragma pack(1) 
    … …  
    8484int     bfb_write_subcmd8(fd_t fd, uint8_t type, uint8_t subtype, uint8_t p1); 
    8585int     bfb_write_subcmd1(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1); 
    86  
    87 /* send a cmd, subcmd packet, add chk (two word parameter) */ 
    8886int     bfb_write_subcmd2(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1, uint16_t p2); 
    89  
    90 /* send a cmd, subcmd packet, add chk (three word parameter) */ 
    9187int     bfb_write_subcmd3(fd_t fd, uint8_t type, uint8_t subtype, uint16_t p1, uint16_t p2, uint16_t p3); 
    92  
    93 /* send a cmd, subcmd packet, add long, word parameter */ 
    9488int     bfb_write_subcmd_lw(fd_t fd, uint8_t type, uint8_t subtype, uint32_t p1, uint16_t p2); 
    9589 

  • trunk/doc/Makefile.am

    r110 r185  
    22# perl's pod2man, pod2html and pod2text needed 
    33 
    4 TOPDIR := .. 
    5 export TOPDIR 
    6 XSLBASE=http://docbook.sourceforge.net/release/xsl/current 
    7  
    8 obexftp.xml: obexftp.tmpl docproc ../obexftp/client.c 
    9         $(top_srcdir)/doc/docproc <$< >$@ 
    10  
    11 docproc_SOURCES = docproc.c 
    12 noinst_PROGRAMS = docproc 
     4EXTRA_DIST =            $(man_MANS) $(noinst_DATA) 
    135 
    146man_MANS =              obexftp.1 obexftpd.1 
    157 
    16 EXTRA_DIST =            $(man_MANS) $(noinst_DATA) \ 
    17                         kernel-doc obexftp.tmpl 
    18  
    19 # transform [A-Z][A-Z]* Change* 
    208noinst_DATA =           obexftp.pod obexftp.1.txt obexftp.1.html \ 
    219                        obexftpd.pod obexftpd.1.txt obexftpd.1.html 
    2210 
    2311if BUILD_DOCS 
    24  
    25 .PHONY: html 
    26  
    27 html: obexftp.html 
    28  
    29 %.html: %.xml 
    30         xsltproc --output $@ $(XSLBASE)/xhtml/docbook.xsl $< 
    3112 
    3213%.1: %.pod 

  • trunk/includes/common.h

    r106 r185  
    1 /* 
    2  * ObexFTP common Macros 
     1/** 
     2        \file includes/common.h 
     3        ObexFTP common macros and debugging. 
     4        ObexFTP library - language bindings for OBEX file transfer. 
    35 */ 
    46 

  • trunk/multicobex/multi_cobex.c

    r156 r185  
    1 /* 
    2  * multi_cobex.c - Talk OBEX over a serial port (Siemens, Ericsson, New-Siemens) 
     1/** 
     2 *  \file multicobex/multi_cobex.c 
     3 *  Detect, initiate and run OBEX over custom serial port protocols 
     4 *  (Siemens, Ericsson, New-Siemens, Motorola, Generic). 
     5 *  ObexFTP library - language bindings for OBEX file transfer. 
    36 * 
    4  *   Copyright (c) 2002-2005 Christian W. Zuckschwerdt <zany@triq.net> 
     7 *   Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    58 * 
    69 *   This program is free software; you can redistribute it and/or modify it 
    … …  
    1922 *      
    2023 */ 
    21 /* 
    22  *       Don, 17 Jan 2002 18:27:25 +0100 
    23  * v0.6  Fre, 15 Feb 2002 15:41:10 +0100 
    24  */ 
    2524 
    2625#ifdef HAVE_CONFIG_H 
    … …  
    9089} 
    9190 
     91/** 
     92        Called from OBEX-lib to set up a connection. 
     93 */ 
    9294int cobex_connect(obex_t *self, void *data) 
    9395{ 
    … …  
    133135} 
    134136 
     137/** 
     138        Called from OBEX-lib to tear down a connection. 
     139 */ 
    135140int cobex_disconnect(obex_t *self, void *data) 
    136141{ 
    … …  
    145150} 
    146151 
    147 /* Called from OBEX-lib when data needs to be written */ 
     152/** 
     153        Called from OBEX-lib when data needs to be written. 
     154 */ 
    148155int cobex_write(obex_t *self, void *data, uint8_t *buffer, int length) 
    149156{ 
    … …  
    192199} 
    193200 
    194 /* Called when input data is needed */ 
     201/** 
     202        Called when input data is needed. 
     203 */ 
    195204int cobex_handleinput(obex_t *self, void *data, int timeout) 
    196205{ 
    … …  
    298307}; 
    299308*/ 
     309 
     310/** 
     311        Create a new multi cobex instance for a given TTY. 
     312 
     313        \param tty the TTY to use. Defaults to the first serial TTY if NULL. 
     314 */ 
    300315obex_ctrans_t *cobex_ctrans (const char *tty) { 
    301316        obex_ctrans_t *ctrans; 
    … …  
    318333} 
    319334 
    320  
     335/** 
     336        Free all data related to a multi cobex instance. 
     337 */ 
    321338void cobex_free (obex_ctrans_t *ctrans) 
    322339{ 

  • trunk/multicobex/multi_cobex.h

    r96 r185  
    1 /* 
    2  * multi_cobex.h 
     1/** 
     2 *  \file multicobex/multi_cobex.h 
     3 *  Detect, initiate and run OBEX over custom serial port protocols 
     4 *  (Siemens, Ericsson, New-Siemens, Motorola, Generic). 
     5 *  ObexFTP library - language bindings for OBEX file transfer. 
    36 * 
    4  *   Copyright (c) 2002-2005 Christian W. Zuckschwerdt <zany@triq.net> 
     7 *   Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    58 *  
    69 *   This program is free software; you can redistribute it and/or modify it 

  • trunk/obexftp/cache.c

    r156 r185  
    1 /* 
    2  *  obexftp/cache.c: ObexFTP client library 
     1/** 
     2 *  \file obexftp/cache.c 
     3 *  ObexFTP client API caching layer. 
     4 *  ObexFTP library - language bindings for OBEX file transfer. 
    35 * 
    4  *  Copyright (c) 2002 Christian W. Zuckschwerdt <zany@triq.net> 
     6 *  Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    57 * 
    68 *  This program is free software; you can redistribute it and/or modify it 
    … …  
    5355 
    5456 
    55 /* 
    56  * Normalize the path argument, add/remove leading/trailing slash 
    57  * turns relative paths into (most likely wrong) absolute ones 
    58  * wont expand "../" or "./" 
     57/** 
     58        Normalize the path argument, add/remove leading/trailing slash 
     59        turns relative paths into (most likely wrong) absolute ones 
     60        wont expand "../" or "./". 
    5961 */ 
    6062static /*@only@*/ char *normalize_dir_path(int quirks, const char *name) 
    … …  
    9092 
    9193 
    92 /* 
    93  * methods that need to invalidate cache lines: 
    94  * setpath (when create is on) 
    95  * put 
    96  * put_file 
    97  * del 
    98  * rename 
     94/** 
     95        Purge all cache object at/below a given path. 
     96        Methods that need to invalidate cache lines: 
     97        - setpath (when create is on) 
     98        - put 
     99        - put_file 
     100        - del 
     101        - rename 
    99102 */ 
    100103void cache_purge(cache_object_t **root, const char *path) 
    … …  
    143146} 
    144147 
     148/** 
     149        Retrieve an object from the cache. 
     150 */ 
    145151int get_cache_object(const obexftp_client_t *cli, const char *name, char **object, int *size) 
    146152{ 
    … …  
    162168} 
    163169 
     170/** 
     171        Store an object in the cache. 
     172 */ 
    164173int put_cache_object(obexftp_client_t *cli, /*@only@*/ char *name, /*@only@*/ char *object, int size) 
    165174{ 
    … …  
    179188} 
    180189 
    181 /* List a directory from cache, optionally loading it first. */ 
     190/** 
     191        List a directory from cache, optionally loading it first. 
     192 */ 
    182193static char *obexftp_cache_list(obexftp_client_t *cli, const char *name) 
    183194{ 
    … …  
    216227/* simple xml parser */ 
    217228 
     229/** 
     230        Parse fixed format date string to time_t. 
     231 */ 
    218232static time_t atotime (const char *date) 
    219233{ 
    … …  
    231245} 
    232246 
    233 /* very limited - not multi-byte character save */ 
    234 /* it is actually "const char *xml" but can't be declared as such */ 
     247/** 
     248        Parse an XML file to array of stat_entry_t's. 
     249        Very limited - not multi-byte character save. 
     250        It's actually "const char *xml" but can't be declared as such. 
     251 */ 
    235252static stat_entry_t *parse_directory(char *xml) 
    236253{ 
    … …  
    340357} dir_stream_t; 
    341358 
     359/** 
     360        Prepare a directory for reading. 
     361 */ 
    342362void *obexftp_opendir(obexftp_client_t *cli, const char *name) 
    343363{ 
    … …  
    367387} 
    368388 
    369 /* the stat entry is a cache object so we do nothing */ 
     389/** 
     390        Close a directory after reading. 
     391        The stat entry is a cache object so we do nothing. 
     392 */ 
    370393int obexftp_closedir(void *dir) { 
    371394        if (!dir) 
    … …  
    375398} 
    376399 
     400/** 
     401        Read the next entry from an open directory. 
     402 */ 
    377403stat_entry_t *obexftp_readdir(void *dir) { 
    378404        dir_stream_t *stream; 
    … …  
    388414} 
    389415          
     416/** 
     417        Stat a directory entry. 
     418 */ 
    390419stat_entry_t *obexftp_stat(obexftp_client_t *cli, const char *name) 
    391420{ 

  • trunk/obexftp/client.c

    r183 r185  
    1 /* 
    2  *  obexftp/client.c: ObexFTP client library 
     1/** 
     2 *  \file obexftp/client.c 
     3 *  ObexFTP client API. 
     4 *  ObexFTP library - language bindings for OBEX file transfer. 
    35 * 
    4  *  Copyright (c) 2002 Christian W. Zuckschwerdt <zany@triq.net> 
     6 *  Copyright (c) 2002-2007 Christian W. Zuckschwerdt <zany@triq.net> 
    57 * 
    68 *  This program is free software; you can redistribute it and/or modify it 
    … …  
    9698#pragma pack() 
    9799 
     100 
    98101#ifdef _WIN32 
    99102#ifdef HAVE_BLUETOOTH 
    … …  
    117120#endif 
    118121 
     122 
     123/** 
     124        Empty callback used as default. 
     125 */ 
    119126static void dummy_info_cb(int UNUSED(event), const char *UNUSED(msg), int UNUSED(len), void *UNUSED(data)) 
    120127{ 
    121         /* dummy */ 
    122 } 
    123  
    124  
    125 /* 
    126  * Normalize the path argument 
    127  * wont turn relative paths into (most likely wrong) absolute ones 
    128  * wont expand "../" or "./" 
     128        /* do nothing */ 
     129} 
     130 
     131 
     132/** 
     133        Normalize the path argument. 
     134        \note 
     135        wont turn relative paths into (most likely wrong) absolute ones. 
     136        wont expand "../" or "./". 
    129137 */ 
    130138/* 
    … …  
    156164*/ 
    157165 
    158 /* 
    159  * Normalize the path argument and split into pathname and basename 
    160  * wont turn relative paths into (most likely wrong) absolute ones 
    161  * wont expand "../" or "./" 
    162  * Will keep "telecom" prefix 
    163  * Do not use this function if there is no slash in the argument! 
     166 
     167/** 
     168        Normalize the path argument and split into pathname and basename. 
     169        \note 
     170        Wont turn relative paths into (most likely wrong) absolute ones. 
     171        Wont expand "../" or "./". 
     172        Will keep "telecom" prefix. 
     173        \warning 
     174        Do not use this function if there is no slash in the argument! 
    164175 */ 
    165176static void split_file_path(const char *name, /*@only@*/ char **basepath, /*@only@*/ char **basename) 
    … …  
    213224 
    214225 
    215 /* Add more data from memory to stream. */ 
     226/** 
     227        Add more data from memory to stream. 
     228 */ 
    216229static int cli_fillstream_from_memory(obexftp_client_t *cli, obex_object_t *object) 
    217230{ 
    … …  
    247260} 
    248261 
    249 /* Add more data from file to stream. */ 
     262 
     263/** 
     264        Add more data from file to stream. 
     265 */ 
    250266static int cli_fillstream_from_file(obexftp_client_t *cli, obex_object_t *object) 
    251267{ 
    … …  
    286302 
    287303 
    288 /* Save body from object or return application parameters */ 
     304/** 
     305        Save body from object or return application parameters. 
     306 */ 
    289307static void client_done(obex_t *handle, obex_object_t *object, int UNUSED(obex_cmd), int UNUSED(obex_rsp)) 
    290308{ 
    … …  
    392410 
    393411 
    394 /* Incoming event from OpenOBEX. */ 
     412/** 
     413        Handle incoming event from OpenOBEX. 
     414 */ 
    395415static void cli_obex_event(obex_t *handle, obex_object_t *object, int UNUSED(mode), int event, int obex_cmd, int obex_rsp) 
    396416{ 
    … …  
    434454 
    435455 
    436 /* Do an OBEX request sync. */ 
     456/** 
     457        Wait for the OBEX client to finish. 
     458 */ 
    437459static int obexftp_sync(obexftp_client_t *cli) 
    438460{ 
    … …  
    457479                return -1; 
    458480} 
    459          
     481 
     482 
     483/** 
     484        Do an OBEX request synchronous. 
     485 */ 
    460486static int cli_sync_request(obexftp_client_t *cli, obex_object_t *object) 
    461487{ 
    … …  
    469495        return obexftp_sync (cli); 
    470496} 
    471          
    472  
    473 /* Create an obexftp client */ 
     497 
     498 
     499/** 
     500        Create an obexftp client. 
     501 
     502        \param transport the transport type that will be used 
     503        \param ctrans optional custom transport (don't use) 
     504        \param infocb optional info callback 
     505        \param infocb_data optional info callback data 
     506 
     507        \return a new all