1 /* 2 * 3 * Copyright 2015 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef GRPC_CORE_LIB_CHANNEL_CHANNEL_ARGS_H 20 #define GRPC_CORE_LIB_CHANNEL_CHANNEL_ARGS_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <grpc/compression.h> 25 #include <grpc/grpc.h> 26 #include "src/core/lib/iomgr/socket_mutator.h" 27 28 // Channel args are intentionally immutable, to avoid the need for locking. 29 30 /** Copy the arguments in \a src into a new instance */ 31 grpc_channel_args* grpc_channel_args_copy(const grpc_channel_args* src); 32 33 /** Copy the arguments in \a src into a new instance, stably sorting keys */ 34 grpc_channel_args* grpc_channel_args_normalize(const grpc_channel_args* src); 35 36 /** Copy the arguments in \a src and append \a to_add. If \a to_add is NULL, it 37 * is equivalent to calling \a grpc_channel_args_copy. */ 38 grpc_channel_args* grpc_channel_args_copy_and_add(const grpc_channel_args* src, 39 const grpc_arg* to_add, 40 size_t num_to_add); 41 42 /** Copies the arguments in \a src except for those whose keys are in 43 \a to_remove. */ 44 grpc_channel_args* grpc_channel_args_copy_and_remove( 45 const grpc_channel_args* src, const char** to_remove, size_t num_to_remove); 46 47 /** Copies the arguments from \a src except for those whose keys are in 48 \a to_remove and appends the arguments in \a to_add. */ 49 grpc_channel_args* grpc_channel_args_copy_and_add_and_remove( 50 const grpc_channel_args* src, const char** to_remove, size_t num_to_remove, 51 const grpc_arg* to_add, size_t num_to_add); 52 53 /** Perform the union of \a a and \a b, prioritizing \a a entries */ 54 grpc_channel_args* grpc_channel_args_union(const grpc_channel_args* a, 55 const grpc_channel_args* b); 56 57 /** Destroy arguments created by \a grpc_channel_args_copy */ 58 void grpc_channel_args_destroy(grpc_channel_args* a); 59 60 /** Returns the compression algorithm set in \a a. */ 61 grpc_compression_algorithm grpc_channel_args_get_compression_algorithm( 62 const grpc_channel_args* a); 63 64 /** Returns a channel arg instance with compression enabled. If \a a is 65 * non-NULL, its args are copied. N.B. GRPC_COMPRESS_NONE disables compression 66 * for the channel. */ 67 grpc_channel_args* grpc_channel_args_set_compression_algorithm( 68 grpc_channel_args* a, grpc_compression_algorithm algorithm); 69 70 /** Sets the support for the given compression algorithm. By default, all 71 * compression algorithms are enabled. It's an error to disable an algorithm set 72 * by grpc_channel_args_set_compression_algorithm. 73 * 74 * Returns an instance with the updated algorithm states. The \a a pointer is 75 * modified to point to the returned instance (which may be different from the 76 * input value of \a a). */ 77 grpc_channel_args* grpc_channel_args_compression_algorithm_set_state( 78 grpc_channel_args** a, grpc_compression_algorithm algorithm, int enabled); 79 80 /** Returns the bitset representing the support state (true for enabled, false 81 * for disabled) for compression algorithms. 82 * 83 * The i-th bit of the returned bitset corresponds to the i-th entry in the 84 * grpc_compression_algorithm enum. */ 85 uint32_t grpc_channel_args_compression_algorithm_get_states( 86 const grpc_channel_args* a); 87 88 int grpc_channel_args_compare(const grpc_channel_args* a, 89 const grpc_channel_args* b); 90 91 /** Returns a channel arg instance with socket mutator added. The socket mutator 92 * will perform its mutate_fd method on all file descriptors used by the 93 * channel. 94 * If \a a is non-MULL, its args are copied. */ 95 grpc_channel_args* grpc_channel_args_set_socket_mutator( 96 grpc_channel_args* a, grpc_socket_mutator* mutator); 97 98 /** Returns the value of argument \a name from \a args, or NULL if not found. */ 99 const grpc_arg* grpc_channel_args_find(const grpc_channel_args* args, 100 const char* name); 101 102 bool grpc_channel_args_want_minimal_stack(const grpc_channel_args* args); 103 104 typedef struct grpc_integer_options { 105 int default_value; // Return this if value is outside of expected bounds. 106 int min_value; 107 int max_value; 108 } grpc_integer_options; 109 110 /** Returns the value of \a arg, subject to the contraints in \a options. */ 111 int grpc_channel_arg_get_integer(const grpc_arg* arg, 112 const grpc_integer_options options); 113 114 /** Returns the value of \a arg if \a arg is of type GRPC_ARG_STRING. 115 Otherwise, emits a warning log, and returns nullptr. 116 If arg is nullptr, returns nullptr, and does not emit a warning. */ 117 char* grpc_channel_arg_get_string(const grpc_arg* arg); 118 119 bool grpc_channel_arg_get_bool(const grpc_arg* arg, bool default_value); 120 121 // Helpers for creating channel args. 122 grpc_arg grpc_channel_arg_string_create(char* name, char* value); 123 grpc_arg grpc_channel_arg_integer_create(char* name, int value); 124 grpc_arg grpc_channel_arg_pointer_create(char* name, void* value, 125 const grpc_arg_pointer_vtable* vtable); 126 127 // Returns a string representing channel args in human-readable form. 128 // Callers takes ownership of result. 129 char* grpc_channel_args_string(const grpc_channel_args* args); 130 131 #endif /* GRPC_CORE_LIB_CHANNEL_CHANNEL_ARGS_H */ 132
