129 lines
4.5 KiB
C
129 lines
4.5 KiB
C
/*
|
|
* Licensed to the Apache Software Foundation (ASF) under one
|
|
* or more contributor license agreements. See the NOTICE file
|
|
* distributed with this work for additional information
|
|
* regarding copyright ownership. The ASF licenses this file
|
|
* to you under the Apache License, Version 2.0 (the
|
|
* "License"); you may not use this file except in compliance
|
|
* with the License. You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing,
|
|
* software distributed under the License is distributed on an
|
|
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
* KIND, either express or implied. See the License for the
|
|
* specific language governing permissions and limitations
|
|
* under the License.
|
|
*/
|
|
|
|
#ifndef GUAC_ARGV_H
|
|
#define GUAC_ARGV_H
|
|
|
|
/**
|
|
* Convenience functions for processing parameter values that are submitted
|
|
* dynamically using "argv" instructions.
|
|
*
|
|
* @file argv.h
|
|
*/
|
|
|
|
#include "argv-constants.h"
|
|
#include "argv-fntypes.h"
|
|
#include "stream-types.h"
|
|
#include "user-fntypes.h"
|
|
|
|
/**
|
|
* Registers the given callback such that it is automatically invoked when an
|
|
* "argv" stream for an argument having the given name is processed using
|
|
* guac_argv_received(). The maximum number of arguments that may be registered
|
|
* in this way is limited by GUAC_ARGV_MAX_REGISTERED. The maximum length of
|
|
* any provided argument name is limited by GUAC_ARGV_MAX_NAME_LENGTH.
|
|
*
|
|
* @see GUAC_ARGV_MAX_NAME_LENGTH
|
|
* @see GUAC_ARGV_MAX_REGISTERED
|
|
*
|
|
* @see GUAC_ARGV_OPTION_ONCE
|
|
* @see GUAC_ARGV_OPTION_ECHO
|
|
*
|
|
* @param name
|
|
* The name of the argument that should be handled by the given callback.
|
|
*
|
|
* @param callback
|
|
* The callback to invoke when the value of an argument having the given
|
|
* name has finished being received.
|
|
*
|
|
* @param data
|
|
* Arbitrary data to be passed to the given callback when a value is
|
|
* received for the given argument.
|
|
*
|
|
* @param options
|
|
* Bitwise OR of all option flags that should affect processing of this
|
|
* argument.
|
|
*
|
|
* @return
|
|
* Zero if the callback was successfully registered, non-zero if the
|
|
* maximum number of registered callbacks has already been reached.
|
|
*/
|
|
int guac_argv_register(const char* name, guac_argv_callback* callback, void* data, int options);
|
|
|
|
/**
|
|
* Waits for receipt of each of the given arguments via guac_argv_received().
|
|
* This function will block until either ALL of the given arguments have been
|
|
* received via guac_argv_received() or until automatic processing of received
|
|
* arguments is stopped with guac_argv_stop().
|
|
*
|
|
* @param args
|
|
* A NULL-terminated array of the names of all arguments that this function
|
|
* should wait for.
|
|
*
|
|
* @return
|
|
* Zero if all of the specified arguments were received, non-zero if
|
|
* guac_argv_stop() was called before all arguments were received.
|
|
*/
|
|
int guac_argv_await(const char** args);
|
|
|
|
/**
|
|
* Hands off management of the given guac_stream, automatically processing data
|
|
* received over that stream as the value of the argument having the given
|
|
* name. The argument must have already been registered with
|
|
* guac_argv_register(). The blob_handler and end_handler of the given stream,
|
|
* if already set, will be overridden without regard to their current value.
|
|
*
|
|
* It is the responsibility of the caller to properly send any required "ack"
|
|
* instructions to accept or reject the received stream.
|
|
*
|
|
* @param stream
|
|
* The guac_stream that will receive the value of the argument having the
|
|
* given name.
|
|
*
|
|
* @param mimetype
|
|
* The mimetype of the data that will be received over the stream.
|
|
*
|
|
* @param name
|
|
* The name of the argument being received.
|
|
*
|
|
* @return
|
|
* Zero if handling of the guac_stream has been successfully handed off,
|
|
* non-zero if the provided argument has not yet been registered with
|
|
* guac_argv_register().
|
|
*/
|
|
int guac_argv_received(guac_stream* stream, const char* mimetype, const char* name);
|
|
|
|
/**
|
|
* Stops further automatic processing of received "argv" streams. Any call to
|
|
* guac_argv_await() that is currently blocking will return, and any future
|
|
* calls to guac_argv_await() will return immediately without blocking.
|
|
*/
|
|
void guac_argv_stop();
|
|
|
|
/**
|
|
* Convenience implementation of the "argv" instruction handler which
|
|
* automatically sends any required "ack" instructions and invokes
|
|
* guac_argv_received(). Only arguments that are registered with
|
|
* guac_argv_register() will be processed.
|
|
*/
|
|
guac_user_argv_handler guac_argv_handler;
|
|
|
|
#endif
|
|
|