cscg24-guacamole

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

argv.h (4609B)

      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_ARGV_H
     21#define GUAC_ARGV_H
     22
     23/**
     24 * Convenience functions for processing parameter values that are submitted
     25 * dynamically using "argv" instructions.
     26 *
     27 * @file argv.h
     28 */
     29
     30#include "argv-constants.h"
     31#include "argv-fntypes.h"
     32#include "stream-types.h"
     33#include "user-fntypes.h"
     34
     35/**
     36 * Registers the given callback such that it is automatically invoked when an
     37 * "argv" stream for an argument having the given name is processed using
     38 * guac_argv_received(). The maximum number of arguments that may be registered
     39 * in this way is limited by GUAC_ARGV_MAX_REGISTERED. The maximum length of
     40 * any provided argument name is limited by GUAC_ARGV_MAX_NAME_LENGTH.
     41 *
     42 * @see GUAC_ARGV_MAX_NAME_LENGTH
     43 * @see GUAC_ARGV_MAX_REGISTERED
     44 *
     45 * @see GUAC_ARGV_OPTION_ONCE
     46 * @see GUAC_ARGV_OPTION_ECHO
     47 *
     48 * @param name
     49 *     The name of the argument that should be handled by the given callback.
     50 *
     51 * @param callback
     52 *     The callback to invoke when the value of an argument having the given
     53 *     name has finished being received.
     54 *
     55 * @param data
     56 *     Arbitrary data to be passed to the given callback when a value is
     57 *     received for the given argument.
     58 *
     59 * @param options
     60 *     Bitwise OR of all option flags that should affect processing of this
     61 *     argument.
     62 *
     63 * @return
     64 *     Zero if the callback was successfully registered, non-zero if the
     65 *     maximum number of registered callbacks has already been reached.
     66 */
     67int guac_argv_register(const char* name, guac_argv_callback* callback, void* data, int options);
     68
     69/**
     70 * Waits for receipt of each of the given arguments via guac_argv_received().
     71 * This function will block until either ALL of the given arguments have been
     72 * received via guac_argv_received() or until automatic processing of received
     73 * arguments is stopped with guac_argv_stop().
     74 *
     75 * @param args
     76 *     A NULL-terminated array of the names of all arguments that this function
     77 *     should wait for.
     78 *
     79 * @return
     80 *     Zero if all of the specified arguments were received, non-zero if
     81 *     guac_argv_stop() was called before all arguments were received.
     82 */
     83int guac_argv_await(const char** args);
     84
     85/**
     86 * Hands off management of the given guac_stream, automatically processing data
     87 * received over that stream as the value of the argument having the given
     88 * name. The argument must have already been registered with
     89 * guac_argv_register(). The blob_handler and end_handler of the given stream,
     90 * if already set, will be overridden without regard to their current value.
     91 *
     92 * It is the responsibility of the caller to properly send any required "ack"
     93 * instructions to accept or reject the received stream.
     94 *
     95 * @param stream
     96 *     The guac_stream that will receive the value of the argument having the
     97 *     given name.
     98 *
     99 * @param mimetype
    100 *     The mimetype of the data that will be received over the stream.
    101 *
    102 * @param name
    103 *     The name of the argument being received.
    104 *
    105 * @return
    106 *     Zero if handling of the guac_stream has been successfully handed off,
    107 *     non-zero if the provided argument has not yet been registered with
    108 *     guac_argv_register().
    109 */
    110int guac_argv_received(guac_stream* stream, const char* mimetype, const char* name);
    111
    112/**
    113 * Stops further automatic processing of received "argv" streams. Any call to
    114 * guac_argv_await() that is currently blocking will return, and any future
    115 * calls to guac_argv_await() will return immediately without blocking.
    116 */
    117void guac_argv_stop();
    118
    119/**
    120 * Convenience implementation of the "argv" instruction handler which
    121 * automatically sends any required "ack" instructions and invokes
    122 * guac_argv_received(). Only arguments that are registered with
    123 * guac_argv_register() will be processed.
    124 */
    125guac_user_argv_handler guac_argv_handler;
    126
    127#endif
    128