Download as
Browse Code »

Commit aee80d5fd592759c7f4f5e1bc29a4f29e7f0c91d

Authored by Perry Werneck
1 parent 5e086dba
Exists in master and in 3 other branches develop, macos, network_module

Updating documentation.

Showing 3 changed files with 86 additions and 53 deletions   Show diff stats
src/include/hostc.h
  Diff comments   View file @aee80d5
... ... @@ -29,16 +29,21 @@
29 29 *
30 30 */
31 31  
32   -/*
33   - * hostc.h
34   - * Global declarations for host.c.
  32 +/**
  33 + * @file hostc.h
  34 + *
  35 + * @brief Global declarations for host.c.
35 36 */
36 37  
37   - #include "api.h"
  38 + #include "api.h"
  39 +
  40 +
  41 +/**
  42 + * @brief Signal a state change.
  43 + */
  44 + LIB3270_INTERNAL void lib3270_st_changed(H3270 *h, LIB3270_STATE tx, int mode);
38 45  
39   -// #define st_changed(tx,mode) lib3270_st_changed(NULL,tx,mode)
  46 + LIB3270_INTERNAL void host_in3270(H3270 *session, LIB3270_CSTATE);
40 47  
41   - LIB3270_INTERNAL void lib3270_st_changed(H3270 *h, LIB3270_STATE tx, int mode);
42   - LIB3270_INTERNAL void host_in3270(H3270 *session, LIB3270_CSTATE);
43   - LIB3270_INTERNAL void host_disconnect(H3270 *h, int disable);
  48 + LIB3270_INTERNAL int host_disconnect(H3270 *h, int failed);
44 49  
... ...
src/include/lib3270.h
  Diff comments   View file @aee80d5
... ... @@ -29,9 +29,17 @@
29 29 *
30 30 */
31 31  
  32 + /**
  33 + * @brief TN3270 API definitions.
  34 + *
  35 + * @author perry.werneck@gmail.com
  36 + *
  37 + */
  38 +
32 39 #ifndef LIB3270_H_INCLUDED
33 40  
34 41 #define LIB3270_H_INCLUDED 1
  42 +
35 43 #include <stdarg.h>
36 44 #include <errno.h>
37 45  
... ... @@ -40,6 +48,7 @@
40 48 #endif // !ENOTCONN
41 49  
42 50 #if defined(__GNUC__)
  51 +
43 52 #define LIB3270_GNUC_FORMAT(s,f) __attribute__ ((__format__ (__printf__, s, f)))
44 53 #define LIB3270_DEPRECATED(func) func __attribute__ ((deprecated))
45 54  
... ... @@ -59,7 +68,7 @@
59 68  
60 69  
61 70 /**
62   - * BIND definitions.
  71 + * @brief BIND definitions.
63 72 */
64 73 #define LIB3270_BIND_RU 0x31
65 74 #define LIB3270_BIND_OFF_PLU_NAME_LEN 26
... ... @@ -73,7 +82,7 @@
73 82 #define LIB3270_LUNAME_LENGTH 16
74 83  
75 84 /**
76   - * Character attributes
  85 + * @brief Character attributes.
77 86 */
78 87 typedef enum _lib3270_attr
79 88 {
... ... @@ -109,6 +118,9 @@
109 118  
110 119 } LIB3270_ATTR;
111 120  
  121 + /**
  122 + * @brief Toogles.
  123 + */
112 124 typedef enum _lib3270_toggle
113 125 {
114 126 LIB3270_TOGGLE_MONOCASE,
... ... @@ -129,14 +141,14 @@
129 141 LIB3270_TOGGLE_SMART_PASTE,
130 142 LIB3270_TOGGLE_BOLD,
131 143 LIB3270_TOGGLE_KEEP_SELECTED,
132   - LIB3270_TOGGLE_UNDERLINE, /**< Show underline ? */
  144 + LIB3270_TOGGLE_UNDERLINE, /**< @brief Show underline ? */
133 145 LIB3270_TOGGLE_CONNECT_ON_STARTUP,
134   - LIB3270_TOGGLE_KP_ALTERNATIVE, /**< Keypad +/- move to next/previous field */
135   - LIB3270_TOGGLE_BEEP, /**< Beep on errors */
136   - LIB3270_TOGGLE_VIEW_FIELD, /**< View Field attribute */
137   - LIB3270_TOGGLE_ALTSCREEN, /**< auto resize on altscreen */
138   - LIB3270_TOGGLE_KEEP_ALIVE, /**< Enable network keep-alive with SO_KEEPALIVE */
139   - LIB3270_TOGGLE_NETWORK_TRACE, /**< Enable network in/out trace */
  146 + LIB3270_TOGGLE_KP_ALTERNATIVE, /**< @brief Keypad +/- move to next/previous field */
  147 + LIB3270_TOGGLE_BEEP, /**< @brief Beep on errors */
  148 + LIB3270_TOGGLE_VIEW_FIELD, /**< @brief View Field attribute */
  149 + LIB3270_TOGGLE_ALTSCREEN, /**< @brief auto resize on altscreen */
  150 + LIB3270_TOGGLE_KEEP_ALIVE, /**< @brief Enable network keep-alive with SO_KEEPALIVE */
  151 + LIB3270_TOGGLE_NETWORK_TRACE, /**< @brief Enable network in/out trace */
140 152  
141 153 LIB3270_TOGGLE_COUNT
142 154  
... ... @@ -313,9 +325,9 @@
313 325 */
314 326 typedef struct _lib3270_field {
315 327  
316   - unsigned short baddr; /**< @brief Address of the field. */
317   - unsigned short length; /**< @brief Field length */
318   - unsigned char attribute; /**< @brief Field attribute */
  328 + unsigned short baddr; /**< @brief Address of the field. */
  329 + unsigned short length; /**< @brief Field length */
  330 + unsigned char attribute; /**< @brief Field attribute */
319 331  
320 332 struct {
321 333 unsigned char foreground; /**< @brief foreground color (0x00 or 0xf) */
... ... @@ -354,7 +366,10 @@
354 366  
355 367 #endif
356 368  
357   - /* State change IDs. */
  369 + /**
  370 + * @brief State change IDs.
  371 + *
  372 + */
358 373 typedef enum _lib3270_state
359 374 {
360 375 LIB3270_STATE_RESOLVING,
... ... @@ -386,7 +401,6 @@
386 401 */
387 402 LIB3270_EXPORT void lib3270_get_screen_size(H3270 *h, int *r, int *c);
388 403  
389   -
390 404 /**
391 405 * Get current screen width in columns.
392 406 *
... ... @@ -414,7 +428,7 @@
414 428 *
415 429 * @param model Terminal model.
416 430 *
417   - * @return Handle of the new session.
  431 + * @return Handle of the new session (release it with lib3270_session_free to avoid memory leaks).
418 432 *
419 433 */
420 434 LIB3270_EXPORT H3270 * lib3270_session_new(const char *model);
... ... @@ -428,7 +442,7 @@
428 442 LIB3270_EXPORT void lib3270_session_free(H3270 *h);
429 443  
430 444 /**
431   - * Register a state change callback.
  445 + * @brief Register a function interested in a state change.
432 446 *
433 447 * @param h Session handle.
434 448 * @param tx State ID
... ... @@ -440,7 +454,7 @@
440 454  
441 455  
442 456 /**
443   - * Set host id for the connect/reconnect operations.
  457 + * @brief Set host id for the connect/reconnect operations.
444 458 *
445 459 * @param h Session handle.
446 460 * @param url URL of host to set in the format tn3270://hostname:service or tn3270s://hostname:service .
... ... @@ -451,7 +465,7 @@
451 465 LIB3270_EXPORT const char * lib3270_set_url(H3270 *h, const char *url);
452 466  
453 467 /**
454   - * Get hostname for the connect/reconnect operations.
  468 + * @brief Get hostname for the connect/reconnect operations.
455 469 *
456 470 * @param h Session handle.
457 471 *
... ... @@ -464,7 +478,7 @@
464 478  
465 479  
466 480 /**
467   - * Get service or port for the connect/reconnect operations.
  481 + * @brief Get service or port for the connect/reconnect operations.
468 482 *
469 483 * @param h Session handle.
470 484 *
... ... @@ -478,7 +492,7 @@
478 492 LIB3270_EXPORT const char * lib3270_get_url(H3270 *h, char *buffer, int len);
479 493  
480 494 /**
481   - * Get session options.
  495 + * @brief Get session options.
482 496 *
483 497 * @param h Session handle.
484 498 *
... ... @@ -486,7 +500,7 @@
486 500 LIB3270_EXPORT LIB3270_OPTION lib3270_get_options(H3270 *hSession);
487 501  
488 502 /**
489   - * Get URL of the hostname for the connect/reconnect operations.
  503 + * @brief Get URL of the hostname for the connect/reconnect operations.
490 504 *
491 505 * @param h Session handle.
492 506 *
... ... @@ -497,7 +511,7 @@
497 511  
498 512  
499 513 /**
500   - * Network connect operation, keep main loop running
  514 + * @brief Network connect operation, keep main loop running
501 515 *
502 516 * @param h Session handle.
503 517 * @param wait Non zero to wait for connection to be ok.
... ... @@ -508,7 +522,7 @@
508 522 LIB3270_EXPORT int lib3270_connect(H3270 *h,int wait);
509 523  
510 524 /**
511   - * Connect to defined host, keep main loop running.
  525 + * @brief Connect to defined host, keep main loop running.
512 526 *
513 527 * @param hSession Session handle.
514 528 * @param hostname Host name.
... ... @@ -534,15 +548,17 @@
534 548 LIB3270_EXPORT int lib3270_connect_url(H3270 *hSession, const char *url, int wait);
535 549  
536 550 /**
537   - * Disconnect from host.
  551 + * @brief Disconnect from host.
538 552 *
539 553 * @param h Session handle.
540 554 *
  555 + * @return -1 if failed (sets errno).
  556 + *
541 557 */
542 558 LIB3270_EXPORT int lib3270_disconnect(H3270 *h);
543 559  
544 560 /**
545   - * Get connection state.
  561 + * @brief Get connection state.
546 562 *
547 563 * @param h Session handle.
548 564 *
... ... @@ -552,7 +568,7 @@
552 568 LIB3270_EXPORT LIB3270_CSTATE lib3270_get_connection_state(H3270 *h);
553 569  
554 570 /**
555   - * Pretend that a sequence of keys was entered at the keyboard.
  571 + * @brief Pretend that a sequence of keys was entered at the keyboard.
556 572 *
557 573 * "Pasting" means that the sequence came from the clipboard. Returns are
558 574 * ignored; newlines mean "move to beginning of next line"; tabs and formfeeds
... ... @@ -585,7 +601,7 @@
585 601 LIB3270_EXPORT int lib3270_translate_to_address(H3270 *hSession, int row, int col);
586 602  
587 603 /**
588   - * Set string at current cursor position.
  604 + * @brief Set string at current cursor position.
589 605 *
590 606 * Returns are ignored; newlines mean "move to beginning of next line";
591 607 * tabs and formfeeds become spaces. Backslashes are not special
... ... @@ -615,7 +631,7 @@
615 631 LIB3270_EXPORT int lib3270_set_cursor_address(H3270 *hSession, int baddr);
616 632  
617 633 /**
618   - * Set cursor position.
  634 + * @brief Set cursor position.
619 635 *
620 636 * @param h Session handle.
621 637 * @param row New cursor row.
... ... @@ -627,7 +643,7 @@
627 643 LIB3270_EXPORT int lib3270_set_cursor_position(H3270 *h, int row, int col);
628 644  
629 645 /**
630   - * get cursor address.
  646 + * @brief Get cursor address.
631 647 *
632 648 * @param hSession Session handle.
633 649 *
... ... @@ -638,7 +654,7 @@
638 654  
639 655  
640 656 /**
641   - * Move cursor
  657 + * @brief Move cursor
642 658 *
643 659 * @param h Session handle.
644 660 * @param dir Direction to move
... ... @@ -649,7 +665,7 @@
649 665 LIB3270_EXPORT int lib3270_move_cursor(H3270 *h, LIB3270_DIRECTION dir, unsigned char sel);
650 666  
651 667 /**
652   - * Print page
  668 + * @brief Print page
653 669 *
654 670 * @param h Session Handle.
655 671 *
... ... @@ -659,7 +675,7 @@
659 675 LIB3270_EXPORT int lib3270_print(H3270 *h);
660 676  
661 677 /**
662   - * Get buffer contents.
  678 + * @brief Get buffer contents.
663 679 *
664 680 * @param h Session handle.
665 681 * @param first First element to get.
... ... @@ -671,7 +687,7 @@
671 687 LIB3270_EXPORT int lib3270_get_contents(H3270 *h, int first, int last, unsigned char *chr, unsigned short *attr);
672 688  
673 689 /**
674   - * get toggle state.
  690 + * @brief get toggle state.
675 691 *
676 692 * @param h Session handle.
677 693 * @param ix Toggle id.
... ... @@ -682,7 +698,7 @@
682 698 LIB3270_EXPORT unsigned char lib3270_get_toggle(H3270 *h, LIB3270_TOGGLE ix);
683 699  
684 700 /**
685   - * Set toggle state.
  701 + * @brief Set toggle state.
686 702 *
687 703 * @param h Session handle.
688 704 * @param ix Toggle id.
... ... @@ -693,7 +709,7 @@
693 709 LIB3270_EXPORT int lib3270_set_toggle(H3270 *h, LIB3270_TOGGLE ix, int value);
694 710  
695 711 /**
696   - * Translate a string toggle name to the corresponding value.
  712 + * @brief Translate a string toggle name to the corresponding value.
697 713 *
698 714 * @param name Toggle name.
699 715 *
... ... @@ -703,7 +719,7 @@
703 719 LIB3270_EXPORT LIB3270_TOGGLE lib3270_get_toggle_id(const char *name);
704 720  
705 721 /**
706   - * Get the toggle name as string.
  722 + * @brief Get the toggle name as string.
707 723 *
708 724 * @param id Toggle id
709 725 *
... ... @@ -713,7 +729,7 @@
713 729 LIB3270_EXPORT const char * lib3270_get_toggle_name(LIB3270_TOGGLE ix);
714 730  
715 731 /**
716   - * Get a long description of the toggle.
  732 + * @brief Get a long description of the toggle.
717 733 *
718 734 * @return Constant string with the toggle description.
719 735 *
... ... @@ -721,7 +737,7 @@
721 737 LIB3270_EXPORT const char * lib3270_get_toggle_description(LIB3270_TOGGLE ix);
722 738  
723 739 /**
724   - * Get a short description of the toggle (for menus).
  740 + * @brief Get a short description of the toggle (for menus).
725 741 *
726 742 * @return Constant string with the toggle label.
727 743 *
... ... @@ -729,7 +745,7 @@
729 745 LIB3270_EXPORT const char * lib3270_get_toggle_label(LIB3270_TOGGLE ix);
730 746  
731 747 /**
732   - * Revert toggle status.
  748 + * @brief Revert toggle status.
733 749 *
734 750 * @param h Session handle.
735 751 * @param ix Toggle id.
... ...
src/lib3270/host.c
  Diff comments   View file @aee80d5
... ... @@ -72,11 +72,10 @@ static void try_reconnect(H3270 *session)
72 72  
73 73 LIB3270_EXPORT int lib3270_disconnect(H3270 *h)
74 74 {
75   - host_disconnect(h,0);
76   - return 0;
  75 + return host_disconnect(h,0);
77 76 }
78 77  
79   -void host_disconnect(H3270 *hSession, int failed)
  78 +int host_disconnect(H3270 *hSession, int failed)
80 79 {
81 80 CHECK_SESSION_HANDLE(hSession);
82 81  
... ... @@ -104,10 +103,19 @@ void host_disconnect(H3270 *hSession, int failed)
104 103 #endif /*]*/
105 104  
106 105 lib3270_set_disconnected(hSession);
  106 +
  107 + return 0;
  108 +
107 109 }
  110 +
  111 + errno = ENOTCONN;
  112 + return -1;
  113 +
108 114 }
109 115  
110   -/* The host has entered 3270 or ANSI mode, or switched between them. */
  116 +/**
  117 + * @brief The host has entered 3270 or ANSI mode, or switched between them.
  118 + */
111 119 void host_in3270(H3270 *hSession, LIB3270_CSTATE new_cstate)
112 120 {
113 121 Boolean now3270 = (new_cstate == LIB3270_CONNECTED_3270 ||
... ... @@ -150,7 +158,9 @@ void lib3270_set_disconnected(H3270 *hSession)
150 158  
151 159 }
152 160  
153   -/* Register a function interested in a state change. */
  161 +/**
  162 + * @brief Register a function interested in a state change.
  163 + */
154 164 LIB3270_EXPORT void lib3270_register_schange(H3270 *h, LIB3270_STATE tx, void (*func)(H3270 *, int, void *),void *data)
155 165 {
156 166 struct lib3270_state_callback *st;
... ... @@ -169,7 +179,9 @@ LIB3270_EXPORT void lib3270_register_schange(H3270 *h, LIB3270_STATE tx, void (*
169 179  
170 180 }
171 181  
172   -/* Signal a state change. */
  182 +/**
  183 + * @brief Signal a state change.
  184 + */
173 185 void lib3270_st_changed(H3270 *h, LIB3270_STATE tx, int mode)
174 186 {
175 187 #if defined(DEBUG)
... ...