uhub/src/adc/message.h

223 lines
7.1 KiB
C
Raw Normal View History

2009-02-19 16:14:09 +00:00
/*
* uhub - A tiny ADC p2p connection hub
* Copyright (C) 2007-2010, Jan Vidar Krey
2009-02-19 16:14:09 +00:00
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
#ifndef HAVE_UHUB_COMMAND_H
#define HAVE_UHUB_COMMAND_H
struct hub_user;
2009-02-19 16:14:09 +00:00
struct adc_message
{
fourcc_t cmd;
sid_t source;
sid_t target;
char* cache;
size_t length;
size_t capacity;
size_t priority;
size_t references;
struct linked_list* feature_cast_include;
struct linked_list* feature_cast_exclude;
};
enum msg_status_level
{
status_level_info = 0, /* Success/informative status message */
status_level_error = 1, /* Recoverable error */
status_level_fatal = 2, /* Fatal error (disconnect) */
};
/**
* Increase the reference counter for an ADC message struct.
* NOTE: Always use the returned value, and not the passed value, as
* it ensures we can actually copy the value if needed.
*/
extern struct adc_message* adc_msg_incref(struct adc_message* msg);
/**
* Decrease the reference counter, and free the memory when apropriate.
*/
extern void adc_msg_free(struct adc_message* msg);
/**
* Perform deep copy a command.
* NOTE: 'references' will be zero for the copied command.
* @return a copy of cmd or NULL if not able to allocate memory.
*/
extern struct adc_message* adc_msg_copy(const struct adc_message* cmd);
/**
* This will parse 'string' and return it as a adc_message struct, or
* NULL if not able to allocate memory or 'string' does not contain
* a valid ADC command.
*
* The message is only considered valid if the user who sent it
* is the rightful origin of the message.
*/
extern struct adc_message* adc_msg_parse_verify(struct hub_user* u, const char* string, size_t length);
2009-02-19 16:14:09 +00:00
/**
* This will parse 'string' and return it as a adc_message struct, or
* NULL if not able to allocate memory or 'string' does not contain
* a valid ADC command.
*/
extern struct adc_message* adc_msg_parse(const char* string, size_t length);
/**
* This will construct a adc_message based on 'string'.
* Only to be used for server generated commands.
*/
extern struct adc_message* adc_msg_create(const char* string);
/**
* Construct a message with the given 'fourcc' and allocate
* 'size' bytes for later use.
*/
extern struct adc_message* adc_msg_construct(fourcc_t fourcc, size_t size);
/**
* Remove a named argument from the command.
*
* @arg prefix a 2 character argument prefix
* @return the number of named arguments removed.
*/
extern int adc_msg_remove_named_argument(struct adc_message* cmd, const char prefix[2]);
/**
* Count the number of arguments matching the given 2 character prefix.
*
* @arg prefix a 2 character argument prefix
* @return the number of matching arguments
*/
extern int adc_msg_has_named_argument(struct adc_message* cmd, const char prefix[2]);
/**
* Returns a named arguments based on the 2 character prefix.
* If multiple matching arguments exists, only the first one will be returned
* by this function.
*
* NOTE: Returned memory must be free'd with hub_free().
*
* @arg prefix a 2 character argument prefix
* @return the argument or NULL if OOM/not found.
*/
extern char* adc_msg_get_named_argument(struct adc_message* cmd, const char prefix[2]);
/**
* Returns a offset of an argument based on the 2 character prefix.
* If multiple matching arguments exists, only the first one will be returned
* by this function.
*
* @arg prefix a 2 character argument prefix
* @return the offset or -1 if the argument is not found.
*/
extern int adc_msg_get_named_argument_index(struct adc_message* cmd, const char prefix[2]);
/**
* @param cmd command to be checked
* @return 1 if the command does not have any arguments (parameters), 0 otherwise, -1 if cmd is invalid.
*/
extern int adc_msg_is_empty(struct adc_message* cmd);
/**
* Returns the argument on the offset position in the command.
* If offset is invalid NULL is returned.
*
* NOTE: Returned memory must be free'd with hub_free().
*
* @return the argument or NULL if OOM/not found.
*/
extern char* adc_msg_get_argument(struct adc_message* cmd, int offset);
/**
* Replace a named argument in the command.
* This will remove any matching arguments (multiple, or none),
* then add 'string' as an argument using the given prefix.
*
* @arg prefix a 2 character argument prefix
* @arg string must be escaped (see adc_msg_escape).
* @return 0 if successful, or -1 if an error occured.
*/
extern int adc_msg_replace_named_argument(struct adc_message* cmd, const char prefix[2], const char* string);
/**
* Append an argument
*
* @arg string must be escaped (see adc_msg_escape).
* @return 0 if successful, or -1 if an error occured (out of memory).
*/
extern int adc_msg_add_argument(struct adc_message* cmd, const char* string);
/**
* Append a named argument
*
* @arg prefix a 2 character argument prefix
* @arg string must be escaped (see adc_msg_escape).
* @return 0 if successful, or -1 if an error occured (out of memory).
*/
extern int adc_msg_add_named_argument(struct adc_message* cmd, const char prefix[2], const char* string);
/**
* Append a string as a named argument.
* The string will automatcally be escaped, if you do not wish to escape th string use adc_msg_add_named_argument() instead.
*
* @arg prefix a 2 character argument prefix
* @arg string must NOT be escaped
* @return 0 if successful, or -1 if an error occured (out of memory).
*/
extern int adc_msg_add_named_argument_string(struct adc_message* cmd, const char prefix[2], const char* string);
/**
* Append an integer as a named argument.
*/
extern int adc_msg_add_named_argument_int(struct adc_message* cmd, const char prefix[2], int integer);
extern int adc_msg_add_named_argument_uint64(struct adc_message* cmd, const char prefix[2], uint64_t num);
2009-02-19 16:14:09 +00:00
/**
* Convert a ADC command escaped string to a regular string.
* @return string or NULL if out of memory
*/
extern char* adc_msg_unescape(const char* string);
/**
* Convert a string to a ADC command escaped string.
* @return adc command escaped string or NULL if out of memory.
*/
extern char* adc_msg_escape(const char* string);
/**
* This will ensure a newline is at the end of the command.
*/
void adc_msg_terminate(struct adc_message* cmd);
/**
* This will remove any newline from the end of the command
*/
void adc_msg_unterminate(struct adc_message* cmd);
/**
* @return the offset for the first command argument in msg->cache.
* or -1 if the command is not understood.
* NOTE: for 'U' and 'C' commands (normally not seen by hubs),
* this returns 4. Should be 4 + lengthOf(cid).
*/
int adc_msg_get_arg_offset(struct adc_message* msg);
#endif /* HAVE_UHUB_COMMAND_H */