home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / oslib / h / buffer < prev    next >
Encoding:
Text File  |  1994-09-07  |  17.7 KB  |  583 lines
  1. #ifndef buffer_H
  2. #define buffer_H
  3.  
  4. /* C header file for Buffer
  5.  * written by DefMod (Sep  7 1994) on Wed Sep  7 21:25:45 1994
  6.  * Copyright © Acorn Computers Ltd, 1994
  7.  */
  8.  
  9. /*************************************************************************
  10.  * This source file was written by Acorn Computers Limited. It is part   *
  11.  * of the OSLib library for writing applications for RISC OS. It may be  *
  12.  * used freely in the creation of programs for RISC OS.                  *
  13.  *************************************************************************/
  14.  
  15. #ifndef types_H
  16.    #include "types.h"
  17. #endif
  18.  
  19. #ifndef os_H
  20.    #include "os.h"
  21. #endif
  22.  
  23. /**********************************
  24.  * SWI names and SWI reason codes *
  25.  **********************************/
  26. #undef  Buffer_Create
  27. #define Buffer_Create                           0x42940
  28. #undef  XBuffer_Create
  29. #define XBuffer_Create                          0x62940
  30. #undef  Buffer_Remove
  31. #define Buffer_Remove                           0x42941
  32. #undef  XBuffer_Remove
  33. #define XBuffer_Remove                          0x62941
  34. #undef  Buffer_Register
  35. #define Buffer_Register                         0x42942
  36. #undef  XBuffer_Register
  37. #define XBuffer_Register                        0x62942
  38. #undef  Buffer_Deregister
  39. #define Buffer_Deregister                       0x42943
  40. #undef  XBuffer_Deregister
  41. #define XBuffer_Deregister                      0x62943
  42. #undef  Buffer_ModifyFlags
  43. #define Buffer_ModifyFlags                      0x42944
  44. #undef  XBuffer_ModifyFlags
  45. #define XBuffer_ModifyFlags                     0x62944
  46. #undef  Buffer_LinkDevice
  47. #define Buffer_LinkDevice                       0x42945
  48. #undef  XBuffer_LinkDevice
  49. #define XBuffer_LinkDevice                      0x62945
  50. #undef  Buffer_UnlinkDevice
  51. #define Buffer_UnlinkDevice                     0x42946
  52. #undef  XBuffer_UnlinkDevice
  53. #define XBuffer_UnlinkDevice                    0x62946
  54. #undef  Buffer_GetInfo
  55. #define Buffer_GetInfo                          0x42947
  56. #undef  XBuffer_GetInfo
  57. #define XBuffer_GetInfo                         0x62947
  58. #undef  Buffer_Threshold
  59. #define Buffer_Threshold                        0x42948
  60. #undef  XBuffer_Threshold
  61. #define XBuffer_Threshold                       0x62948
  62. #undef  Buffer_InternalInfo
  63. #define Buffer_InternalInfo                     0x42949
  64. #undef  XBuffer_InternalInfo
  65. #define XBuffer_InternalInfo                    0x62949
  66. #undef  InsV
  67. #define InsV                                    0x14
  68. #undef  InsV_Block
  69. #define InsV_Block                              0x14
  70. #undef  RemV
  71. #define RemV                                    0x15
  72. #undef  RemV_Block
  73. #define RemV_Block                              0x15
  74. #undef  CnpV
  75. #define CnpV                                    0x16
  76. #undef  Service_BufferStarting
  77. #define Service_BufferStarting                  0x6F
  78. #undef  Event_OutputBufferEmpty
  79. #define Event_OutputBufferEmpty                 0x0
  80. #undef  Event_InputBufferFull
  81. #define Event_InputBufferFull                   0x1
  82. #undef  Event_InputBufferFullBlockOp
  83. #define Event_InputBufferFullBlockOp            0x1
  84. #undef  UpCall_BufferFilling
  85. #define UpCall_BufferFilling                    0x8
  86. #undef  UpCall_BufferEmptying
  87. #define UpCall_BufferEmptying                   0x9
  88.  
  89. /************************************
  90.  * Structure and union declarations *
  91.  ************************************/
  92. typedef struct buffer_b_                        *buffer_b;
  93. typedef struct buffer_internal_id_              *buffer_internal_id;
  94. typedef struct buffer_mouse_data                buffer_mouse_data;
  95.  
  96. /********************
  97.  * Type definitions *
  98.  ********************/
  99. struct buffer_mouse_data
  100.    {  short x;
  101.       short y;
  102.       byte buttons;
  103.       byte time [4];
  104.    };
  105.  
  106. /************************
  107.  * Constant definitions *
  108.  ************************/
  109. #define buffer_KEYBOARD                         0
  110. #define buffer_RS423_INPUT                      1
  111. #define buffer_RS423_OUTPUT                     2
  112. #define buffer_PRINTER                          3
  113. #define buffer_SOUND_CHANNEL0                   4
  114. #define buffer_SOUND_CHANNEL1                   5
  115. #define buffer_SOUND_CHANNEL2                   6
  116. #define buffer_SOUND_CHANNEL3                   7
  117. #define buffer_SPEECH                           8
  118. #define buffer_MOUSE                            9
  119. #define buffer_DORMANT                          0x1u
  120. #define buffer_EVENT_ON_EMPTY                   0x2u
  121. #define buffer_EVENT_ON_FULL                    0x4u
  122. #define buffer_UP_CALL_ON_THRESHOLD             0x8u
  123. #define error_BUFFER_MANAGER_BAD_SWI            0x20700u
  124. #define error_BUFFER_MANAGER_TOO_MANY_BUFFERS   0x20700u
  125. #define error_BUFFER_MANAGER_BAD_BUFFER         0x20700u
  126. #define error_BUFFER_MANAGER_IN_USE             0x20700u
  127. #define error_BUFFER_MANAGER_UNABLE_TO_DETACH   0x20700u
  128. #define error_BUFFER_MANAGER_HANDLE_ALREADY_USED 0x20700u
  129. #define error_BUFFER_MANAGER_BUFFER_TOO_SMALL   0x20700u
  130. #define error_BUFFER_MANAGER_BAD_PARM           0x20700u
  131. #define cnpv_COUNT_ENTRIES                      0x0u
  132. #define cnpv_NUMBER_FREE                        0x20000000u
  133. #define cnpv_PURGE                              0x10000000u
  134.  
  135. /*************************
  136.  * Function declarations *
  137.  *************************/
  138.  
  139. #ifdef __cplusplus
  140.    extern "C" {
  141. #endif
  142.  
  143. /*************************************************************
  144.  * NOTE: The following functions provide direct access to    *
  145.  *       the SWI's noted in the function description.        *
  146.  *       Please read the relevant PRM section for more       *
  147.  *       information on their input/output parameters.       *
  148.  *************************************************************/
  149.  
  150. /* ------------------------------------------------------------------------
  151.  * Function:      buffer_create()
  152.  *
  153.  * Description:   Claims an area of memory from the RMA and registers it as
  154.  *                a buffer
  155.  *
  156.  * Input:         flags - value of R0 on entry
  157.  *                size - value of R1 on entry
  158.  *                b - value of R2 on entry
  159.  *
  160.  * Output:        b_out - value of R0 on exit (X version only)
  161.  *
  162.  * Returns:       R0 (non-X version only)
  163.  *
  164.  * Other notes:   Calls SWI 0x42940.
  165.  */
  166.  
  167. extern os_error *xbuffer_create (bits flags,
  168.       int size,
  169.       buffer_b b,
  170.       buffer_b *b_out);
  171. extern buffer_b buffer_create (bits flags,
  172.       int size,
  173.       buffer_b b);
  174.  
  175. /* ------------------------------------------------------------------------
  176.  * Function:      buffer_remove()
  177.  *
  178.  * Description:   Deregisters a buffer and frees its memory
  179.  *
  180.  * Input:         b - value of R0 on entry
  181.  *
  182.  * Other notes:   Calls SWI 0x42941.
  183.  */
  184.  
  185. extern os_error *xbuffer_remove (buffer_b b);
  186. extern void buffer_remove (buffer_b b);
  187.  
  188. /* ------------------------------------------------------------------------
  189.  * Function:      buffer_register()
  190.  *
  191.  * Description:   Registers an area of memory as a buffer
  192.  *
  193.  * Input:         flags - value of R0 on entry
  194.  *                buffer - value of R1 on entry
  195.  *                end - value of R2 on entry
  196.  *                b - value of R3 on entry
  197.  *
  198.  * Output:        b_out - value of R0 on exit (X version only)
  199.  *
  200.  * Returns:       R0 (non-X version only)
  201.  *
  202.  * Other notes:   Calls SWI 0x42942.
  203.  */
  204.  
  205. extern os_error *xbuffer_register (bits flags,
  206.       byte *buffer,
  207.       byte *end,
  208.       buffer_b b,
  209.       buffer_b *b_out);
  210. extern buffer_b buffer_register (bits flags,
  211.       byte *buffer,
  212.       byte *end,
  213.       buffer_b b);
  214.  
  215. /* ------------------------------------------------------------------------
  216.  * Function:      buffer_deregister()
  217.  *
  218.  * Description:   Deregisters a buffer
  219.  *
  220.  * Input:         b - value of R0 on entry
  221.  *
  222.  * Other notes:   Calls SWI 0x42943.
  223.  */
  224.  
  225. extern os_error *xbuffer_deregister (buffer_b b);
  226. extern void buffer_deregister (buffer_b b);
  227.  
  228. /* ------------------------------------------------------------------------
  229.  * Function:      buffer_modify_flags()
  230.  *
  231.  * Description:   Modifies a buffer's flags word
  232.  *
  233.  * Input:         b - value of R0 on entry
  234.  *                eor_mask - value of R1 on entry
  235.  *                and_mask - value of R2 on entry
  236.  *
  237.  * Other notes:   Calls SWI 0x42944.
  238.  */
  239.  
  240. extern os_error *xbuffer_modify_flags (buffer_b b,
  241.       bits eor_mask,
  242.       bits and_mask);
  243. extern void buffer_modify_flags (buffer_b b,
  244.       bits eor_mask,
  245.       bits and_mask);
  246.  
  247. /* ------------------------------------------------------------------------
  248.  * Function:      buffer_link_device()
  249.  *
  250.  * Description:   Links a set of routines to a specified buffer
  251.  *
  252.  * Input:         b - value of R0 on entry
  253.  *                wakeup_code - value of R1 on entry
  254.  *                owner_change_code - value of R2 on entry
  255.  *                handle - value of R3 on entry
  256.  *                workspace - value of R4 on entry
  257.  *
  258.  * Other notes:   Calls SWI 0x42945.
  259.  */
  260.  
  261. extern os_error *xbuffer_link_device (buffer_b b,
  262.       void *wakeup_code,
  263.       void *owner_change_code,
  264.       int handle,
  265.       void *workspace);
  266. extern void buffer_link_device (buffer_b b,
  267.       void *wakeup_code,
  268.       void *owner_change_code,
  269.       int handle,
  270.       void *workspace);
  271.  
  272. /* ------------------------------------------------------------------------
  273.  * Function:      buffer_unlink_device()
  274.  *
  275.  * Description:   Unlinks a set of routines from the specified buffer
  276.  *
  277.  * Input:         b - value of R0 on entry
  278.  *
  279.  * Other notes:   Calls SWI 0x42946.
  280.  */
  281.  
  282. extern os_error *xbuffer_unlink_device (buffer_b b);
  283. extern void buffer_unlink_device (buffer_b b);
  284.  
  285. /* ------------------------------------------------------------------------
  286.  * Function:      buffer_get_info()
  287.  *
  288.  * Description:   Returns data about the buffer
  289.  *
  290.  * Input:         b - value of R0 on entry
  291.  *
  292.  * Output:        flags - value of R0 on exit
  293.  *                buffer - value of R1 on exit
  294.  *                end - value of R2 on exit
  295.  *                insertion_point - value of R3 on exit
  296.  *                removal_point - value of R4 on exit
  297.  *                spare - value of R5 on exit
  298.  *                used - value of R6 on exit
  299.  *
  300.  * Other notes:   Calls SWI 0x42947.
  301.  */
  302.  
  303. extern os_error *xbuffer_get_info (buffer_b b,
  304.       bits *flags,
  305.       byte **buffer,
  306.       byte **end,
  307.       int *insertion_point,
  308.       int *removal_point,
  309.       int *spare,
  310.       int *used);
  311. extern void buffer_get_info (buffer_b b,
  312.       bits *flags,
  313.       byte **buffer,
  314.       byte **end,
  315.       int *insertion_point,
  316.       int *removal_point,
  317.       int *spare,
  318.       int *used);
  319.  
  320. /* ------------------------------------------------------------------------
  321.  * Function:      buffer_threshold()
  322.  *
  323.  * Description:   Sets or reads the warning threshold of the buffer
  324.  *
  325.  * Input:         b - value of R0 on entry
  326.  *                threshold - value of R1 on entry
  327.  *
  328.  * Output:        old_threshold - value of R1 on exit (X version only)
  329.  *
  330.  * Returns:       R1 (non-X version only)
  331.  *
  332.  * Other notes:   Calls SWI 0x42948.
  333.  */
  334.  
  335. extern os_error *xbuffer_threshold (buffer_b b,
  336.       int threshold,
  337.       int *old_threshold);
  338. extern int buffer_threshold (buffer_b b,
  339.       int threshold);
  340.  
  341. /* ------------------------------------------------------------------------
  342.  * Function:      buffer_internal_info()
  343.  *
  344.  * Description:   Converts a buffer handle into a buffer manager internal
  345.  *                id
  346.  *
  347.  * Input:         b - value of R0 on entry
  348.  *
  349.  * Output:        id - value of R0 on exit
  350.  *                service_routine - value of R1 on exit
  351.  *                workspace - value of R2 on exit
  352.  *
  353.  * Other notes:   Calls SWI 0x42949.
  354.  */
  355.  
  356. extern os_error *xbuffer_internal_info (buffer_b b,
  357.       buffer_internal_id *id,
  358.       void **service_routine,
  359.       void **workspace);
  360. extern void buffer_internal_info (buffer_b b,
  361.       buffer_internal_id *id,
  362.       void **service_routine,
  363.       void **workspace);
  364.  
  365. /* ------------------------------------------------------------------------
  366.  * Function:      insv()
  367.  *
  368.  * Description:   Called to place a byte in a buffer
  369.  *
  370.  * Input:         b - value of R0 on entry
  371.  *                buffer_no - value of R1 on entry
  372.  *
  373.  * Output:        psr - processor status register on exit (X version only)
  374.  *
  375.  * Returns:       psr (non-X version only)
  376.  *
  377.  * Other notes:   Calls SWI 0x34 with R9 = 0x14.
  378.  */
  379.  
  380. extern os_error *xinsv (byte b,
  381.       int buffer_no,
  382.       bits *psr);
  383. extern bits insv (byte b,
  384.       int buffer_no);
  385.  
  386. /* ------------------------------------------------------------------------
  387.  * Function:      insv_block()
  388.  *
  389.  * Description:   Called to place a block in a buffer
  390.  *
  391.  * Input:         buffer_no - value of R1 on entry
  392.  *                data - value of R2 on entry
  393.  *                size - value of R3 on entry
  394.  *
  395.  * Output:        end - value of R2 on exit
  396.  *                psr - processor status register on exit (X version only)
  397.  *
  398.  * Returns:       psr (non-X version only)
  399.  *
  400.  * Other notes:   Calls SWI 0x34 with R1 |= 0x80000000, R9 = 0x14.
  401.  */
  402.  
  403. extern os_error *xinsv_block (int buffer_no,
  404.       byte *data,
  405.       int size,
  406.       byte **end,
  407.       bits *psr);
  408. extern bits insv_block (int buffer_no,
  409.       byte *data,
  410.       int size,
  411.       byte **end);
  412.  
  413. /* ------------------------------------------------------------------------
  414.  * Function:      remv()
  415.  *
  416.  * Description:   Called to remove a byte from a buffer, or examine the
  417.  *                next one (not implemented)
  418.  *
  419.  * Input:         buffer_no - value of R1 on entry
  420.  *
  421.  * Output:        examined_b - value of R0 on exit
  422.  *                removed_b - value of R2 on exit
  423.  *                psr - processor status register on exit (X version only)
  424.  *
  425.  * Returns:       psr (non-X version only)
  426.  *
  427.  * Other notes:   Calls SWI 0x34 with R9 = 0x15.
  428.  */
  429.  
  430. extern os_error *xremv (int buffer_no,
  431.       byte *examined_b,
  432.       byte *removed_b,
  433.       bits *psr);
  434. extern bits remv (int buffer_no,
  435.       byte *examined_b,
  436.       byte *removed_b);
  437.  
  438. /* ------------------------------------------------------------------------
  439.  * Function:      remv_block()
  440.  *
  441.  * Description:   Called to remove a block from a buffer, or examine it
  442.  *                (not implemented)
  443.  *
  444.  * Input:         buffer_no - value of R1 on entry
  445.  *                buffer - value of R2 on entry
  446.  *                byte_count - value of R3 on entry
  447.  *
  448.  * Output:        end - value of R2 on exit
  449.  *                spare - value of R3 on exit
  450.  *                psr - processor status register on exit (X version only)
  451.  *
  452.  * Returns:       psr (non-X version only)
  453.  *
  454.  * Other notes:   Calls SWI 0x34 with R1 |= 0x80000000, R9 = 0x15.
  455.  */
  456.  
  457. extern os_error *xremv_block (int buffer_no,
  458.       byte *buffer,
  459.       int byte_count,
  460.       byte **end,
  461.       int *spare,
  462.       bits *psr);
  463. extern bits remv_block (int buffer_no,
  464.       byte *buffer,
  465.       int byte_count,
  466.       byte **end,
  467.       int *spare);
  468.  
  469. /* ------------------------------------------------------------------------
  470.  * Function:      cnpv()
  471.  *
  472.  * Description:   Called to count the entries or the number of free bytes
  473.  *                left in a buffer, or to purge the contents of a buffer
  474.  *                (not implemented)
  475.  *
  476.  * Input:         buffer_no - value of R1 on entry
  477.  *
  478.  * Output:        lo8bits - value of R1 on exit
  479.  *                hi24bits - value of R2 on exit
  480.  *
  481.  * Other notes:   Calls SWI 0x34 with R9 = 0x16.
  482.  */
  483.  
  484. extern os_error *xcnpv (int buffer_no,
  485.       bits *lo8bits,
  486.       bits *hi24bits);
  487. extern void cnpv (int buffer_no,
  488.       bits *lo8bits,
  489.       bits *hi24bits);
  490.  
  491. /* ------------------------------------------------------------------------
  492.  * Function:      service_buffer_starting()
  493.  *
  494.  * Description:   Notifies modules that the buffer manager is starting
  495.  *
  496.  * Other notes:   Calls SWI 0x30 with R1 = 0x6F.
  497.  */
  498.  
  499. extern os_error *xservice_buffer_starting (void);
  500. extern void service_buffer_starting (void);
  501.  
  502. /* ------------------------------------------------------------------------
  503.  * Function:      event_output_buffer_empty()
  504.  *
  505.  * Description:   Output buffer empty
  506.  *
  507.  * Input:         buffer - value of R1 on entry
  508.  *
  509.  * Other notes:   Calls SWI 0x22 with R0 = 0x0.
  510.  */
  511.  
  512. extern os_error *xevent_output_buffer_empty (int buffer);
  513. extern void event_output_buffer_empty (int buffer);
  514.  
  515. /* ------------------------------------------------------------------------
  516.  * Function:      event_input_buffer_full()
  517.  *
  518.  * Description:   Input buffer full
  519.  *
  520.  * Input:         buffer - value of R1 on entry
  521.  *                b - value of R2 on entry
  522.  *
  523.  * Other notes:   Calls SWI 0x22 with R0 = 0x1.
  524.  */
  525.  
  526. extern os_error *xevent_input_buffer_full (int buffer,
  527.       byte b);
  528. extern void event_input_buffer_full (int buffer,
  529.       byte b);
  530.  
  531. /* ------------------------------------------------------------------------
  532.  * Function:      event_input_buffer_full_block_op()
  533.  *
  534.  * Description:   Input buffer full on block operation
  535.  *
  536.  * Input:         buffer - value of R1 on entry
  537.  *                data - value of R2 on entry
  538.  *                count - value of R3 on entry
  539.  *
  540.  * Other notes:   Calls SWI 0x22 with R0 = 0x1, R1 |= 0x80000000.
  541.  */
  542.  
  543. extern os_error *xevent_input_buffer_full_block_op (int buffer,
  544.       byte *data,
  545.       int count);
  546. extern void event_input_buffer_full_block_op (int buffer,
  547.       byte *data,
  548.       int count);
  549.  
  550. /* ------------------------------------------------------------------------
  551.  * Function:      upcall_buffer_filling()
  552.  *
  553.  * Description:   A buffer's free space has become less than its specified
  554.  *                threshold
  555.  *
  556.  * Input:         b - value of R1 on entry
  557.  *
  558.  * Other notes:   Calls SWI 0x33 with R0 = 0x8, R2 = 0x0.
  559.  */
  560.  
  561. extern os_error *xupcall_buffer_filling (buffer_b b);
  562. extern void upcall_buffer_filling (buffer_b b);
  563.  
  564. /* ------------------------------------------------------------------------
  565.  * Function:      upcall_buffer_emptying()
  566.  *
  567.  * Description:   A buffer's free space has become not less than its
  568.  *                specified threshold
  569.  *
  570.  * Input:         b - value of R1 on entry
  571.  *
  572.  * Other notes:   Calls SWI 0x33 with R0 = 0x9, R2 = 0xFFFFFFFF.
  573.  */
  574.  
  575. extern os_error *xupcall_buffer_emptying (buffer_b b);
  576. extern void upcall_buffer_emptying (buffer_b b);
  577.  
  578. #ifdef __cplusplus
  579.    }
  580. #endif
  581.  
  582. #endif
  583.