/*
 * 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