cscg24-guacamole

CSCG 2024 Challenge 'Guacamole Mashup'
git clone https://git.sinitax.com/sinitax/cscg24-guacamole
Log | Files | Refs | sfeed.txt

socket-fntypes.h (4309B)

      1/*
      2 * Licensed to the Apache Software Foundation (ASF) under one
      3 * or more contributor license agreements.  See the NOTICE file
      4 * distributed with this work for additional information
      5 * regarding copyright ownership.  The ASF licenses this file
      6 * to you under the Apache License, Version 2.0 (the
      7 * "License"); you may not use this file except in compliance
      8 * with the License.  You may obtain a copy of the License at
      9 *
     10 *   http://www.apache.org/licenses/LICENSE-2.0
     11 *
     12 * Unless required by applicable law or agreed to in writing,
     13 * software distributed under the License is distributed on an
     14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     15 * KIND, either express or implied.  See the License for the
     16 * specific language governing permissions and limitations
     17 * under the License.
     18 */
     19
     20#ifndef _GUAC_SOCKET_FNTYPES_H
     21#define _GUAC_SOCKET_FNTYPES_H
     22
     23/**
     24 * Function type definitions related to the guac_socket object.
     25 *
     26 * @file socket-fntypes.h
     27 */
     28
     29#include "socket-types.h"
     30
     31#include <unistd.h>
     32
     33/**
     34 * Generic read handler for socket read operations, modeled after the standard
     35 * POSIX read() function. When set within a guac_socket, a handler of this type
     36 * will be called when data needs to be read into the socket.
     37 *
     38 * @param socket The guac_socket being read from.
     39 * @param buf The arbitrary buffer we must populate with data.
     40 * @param count The maximum number of bytes to read into the buffer.
     41 * @return The number of bytes read, or -1 if an error occurs.
     42 */
     43typedef ssize_t guac_socket_read_handler(guac_socket* socket,
     44        void* buf, size_t count);
     45
     46/**
     47 * Generic write handler for socket write operations, modeled after the standard
     48 * POSIX write() function. When set within a guac_socket, a handler of this type
     49 * will be called when data needs to be written to the socket.
     50 *
     51 * @param socket The guac_socket being written to.
     52 * @param buf The arbitrary buffer containing data to be written.
     53 * @param count The maximum number of bytes to written to the buffer.
     54 * @return The number of bytes written, or -1 if an error occurs.
     55 */
     56typedef ssize_t guac_socket_write_handler(guac_socket* socket,
     57        const void* buf, size_t count);
     58
     59/**
     60 * Generic handler for socket select operations, similar to the POSIX select()
     61 * function. When guac_socket_select() is called on a guac_socket, its
     62 * guac_socket_select_handler will be invoked, if defined.
     63 *
     64 * @param socket The guac_socket being selected.
     65 * @param usec_timeout The maximum number of microseconds to wait for data, or
     66 *                     -1 to potentially wait forever.
     67 * @return Positive on success, zero if the timeout elapsed and no data is
     68 *         available, negative on error.
     69 */
     70typedef int guac_socket_select_handler(guac_socket* socket, int usec_timeout);
     71
     72/**
     73 * Generic flush handler for socket flush operations. This function is not
     74 * modeled after any POSIX function. When set within a guac_socket, a handler
     75 * of this type will be called when guac_socket_flush() is called.
     76 *
     77 * @param socket
     78 *     The guac_socket being flushed.
     79 *
     80 * @return
     81 *     Zero on success, or non-zero if an error occurs during flush.
     82 */
     83typedef ssize_t guac_socket_flush_handler(guac_socket* socket);
     84
     85/**
     86 * When set within a guac_socket, a handler of this type will be called
     87 * whenever exclusive access to the guac_socket is required, such as when
     88 * guac_socket_instruction_begin() is called.
     89 *
     90 * @param socket
     91 *     The guac_socket to which exclusive access is required.
     92 */
     93typedef void guac_socket_lock_handler(guac_socket* socket);
     94
     95/**
     96 * When set within a guac_socket, a handler of this type will be called
     97 * whenever exclusive access to the guac_socket is no longer required, such as
     98 * when guac_socket_instruction_end() is called.
     99 *
    100 * @param socket
    101 *     The guac_socket to which exclusive access is no longer required.
    102 */
    103typedef void guac_socket_unlock_handler(guac_socket* socket);
    104
    105/**
    106 * Generic handler for the closing of a socket, modeled after the standard
    107 * POSIX close() function. When set within a guac_socket, a handler of this type
    108 * will be called when the socket is closed.
    109 *
    110 * @param socket The guac_socket being closed.
    111 * @return Zero on success, or -1 if an error occurs.
    112 */
    113typedef int guac_socket_free_handler(guac_socket* socket);
    114
    115#endif
    116