grpc.h

Go to the documentation of this file.

/*
 *
 * Copyright 2015-2016, Google Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *     * Neither the name of Google Inc. nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef GRPC_GRPC_H
#define GRPC_GRPC_H

#include <grpc/status.h>

#include <grpc/byte_buffer.h>
#include <grpc/impl/codegen/connectivity_state.h>
#include <grpc/impl/codegen/grpc_types.h>
#include <grpc/impl/codegen/propagation_bits.h>
#include <grpc/slice.h>
#include <grpc/support/time.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

GRPCAPI void grpc_metadata_array_init(grpc_metadata_array *array);
GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array *array);

GRPCAPI void grpc_call_details_init(grpc_call_details *details);
GRPCAPI void grpc_call_details_destroy(grpc_call_details *details);

GRPCAPI void grpc_register_plugin(void (*init)(void), void (*destroy)(void));

GRPCAPI void grpc_init(void);

GRPCAPI void grpc_shutdown(void);

GRPCAPI const char *grpc_version_string(void);

GRPCAPI const char *grpc_g_stands_for(void);

typedef enum {
  /* Events are popped out by calling grpc_completion_queue_next() API ONLY */
  GRPC_CQ_NEXT = 1,

  /* Events are popped out by calling grpc_completion_queue_pluck() API ONLY */
  GRPC_CQ_PLUCK
} grpc_cq_completion_type;

typedef enum {
  GRPC_CQ_DEFAULT_POLLING,

  /* Similar to GRPC_CQ_DEFAULT_POLLING except that the completion queues will
     not contain any 'listening file descriptors' (i.e file descriptors used to
     listen to incoming channels) */
  GRPC_CQ_NON_LISTENING,

  /* The completion queue will not have an associated pollset. Note that
     grpc_completion_queue_next() or grpc_completion_queue_pluck() MUST still be
     called to pop events from the completion queue; it is not required to call
     them actively to make I/O progress */
  GRPC_CQ_NON_POLLING
} grpc_cq_polling_type;

#define GRPC_CQ_CURRENT_VERSION 1
typedef struct grpc_completion_queue_attributes {
  /* The version number of this structure. More fields might be added to this
     structure in future. */
  int version; /* Set to GRPC_CQ_CURRENT_VERSION */

  grpc_cq_completion_type cq_completion_type;

  grpc_cq_polling_type cq_polling_type;
} grpc_completion_queue_attributes;

typedef struct grpc_completion_queue_factory grpc_completion_queue_factory;

GRPCAPI const grpc_completion_queue_factory *
grpc_completion_queue_factory_lookup(
    const grpc_completion_queue_attributes *attributes);

GRPCAPI grpc_completion_queue *grpc_completion_queue_create_for_next(
    void *reserved);

GRPCAPI grpc_completion_queue *grpc_completion_queue_create_for_pluck(
    void *reserved);

GRPCAPI grpc_completion_queue *grpc_completion_queue_create(void *reserved);

GRPCAPI grpc_event grpc_completion_queue_next(grpc_completion_queue *cq,
                                              gpr_timespec deadline,
                                              void *reserved);

GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq,
                                               void *tag, gpr_timespec deadline,
                                               void *reserved);

#define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6

GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue *cq);

GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue *cq);

GRPCAPI grpc_alarm *grpc_alarm_create(grpc_completion_queue *cq,
                                      gpr_timespec deadline, void *tag);

GRPCAPI void grpc_alarm_cancel(grpc_alarm *alarm);

GRPCAPI void grpc_alarm_destroy(grpc_alarm *alarm);

GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state(
    grpc_channel *channel, int try_to_connect);

GRPCAPI void grpc_channel_watch_connectivity_state(
    grpc_channel *channel, grpc_connectivity_state last_observed_state,
    gpr_timespec deadline, grpc_completion_queue *cq, void *tag);

GRPCAPI grpc_call *grpc_channel_create_call(
    grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask,
    grpc_completion_queue *completion_queue, grpc_slice method,
    const grpc_slice *host, gpr_timespec deadline, void *reserved);

GRPCAPI void grpc_channel_ping(grpc_channel *channel, grpc_completion_queue *cq,
                               void *tag, void *reserved);

GRPCAPI void *grpc_channel_register_call(grpc_channel *channel,
                                         const char *method, const char *host,
                                         void *reserved);

GRPCAPI grpc_call *grpc_channel_create_registered_call(
    grpc_channel *channel, grpc_call *parent_call, uint32_t propagation_mask,
    grpc_completion_queue *completion_queue, void *registered_call_handle,
    gpr_timespec deadline, void *reserved);

GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call *call,
                                              const grpc_op *ops, size_t nops,
                                              void *tag, void *reserved);

GRPCAPI char *grpc_call_get_peer(grpc_call *call);

struct grpc_load_reporting_cost_context;

/* Associate costs contained in \a cost_context to \a call. */
GRPCAPI void grpc_call_set_load_reporting_cost_context(
    grpc_call *call, struct grpc_load_reporting_cost_context *context);

struct census_context;

GRPCAPI void grpc_census_call_set_context(grpc_call *call,
                                          struct census_context *context);

GRPCAPI struct census_context *grpc_census_call_get_context(grpc_call *call);

GRPCAPI char *grpc_channel_get_target(grpc_channel *channel);

GRPCAPI void grpc_channel_get_info(grpc_channel *channel,
                                   const grpc_channel_info *channel_info);

GRPCAPI grpc_channel *grpc_insecure_channel_create(
    const char *target, const grpc_channel_args *args, void *reserved);

GRPCAPI grpc_channel *grpc_lame_client_channel_create(
    const char *target, grpc_status_code error_code, const char *error_message);

GRPCAPI void grpc_channel_destroy(grpc_channel *channel);

/* Error handling for grpc_call
   Most grpc_call functions return a grpc_error. If the error is not GRPC_OK
   then the operation failed due to some unsatisfied precondition.
   If a grpc_call fails, it's guaranteed that no change to the call state
   has been made. */

GRPCAPI grpc_call_error grpc_call_cancel(grpc_call *call, void *reserved);

GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call *call,
                                                     grpc_status_code status,
                                                     const char *description,
                                                     void *reserved);

GRPCAPI void grpc_call_destroy(grpc_call *call);

GRPCAPI grpc_call_error grpc_server_request_call(
    grpc_server *server, grpc_call **call, grpc_call_details *details,
    grpc_metadata_array *request_metadata,
    grpc_completion_queue *cq_bound_to_call,
    grpc_completion_queue *cq_for_notification, void *tag_new);

typedef enum {
  GRPC_SRM_PAYLOAD_NONE,
  GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER
} grpc_server_register_method_payload_handling;

GRPCAPI void *grpc_server_register_method(
    grpc_server *server, const char *method, const char *host,
    grpc_server_register_method_payload_handling payload_handling,
    uint32_t flags);

GRPCAPI grpc_call_error grpc_server_request_registered_call(
    grpc_server *server, void *registered_method, grpc_call **call,
    gpr_timespec *deadline, grpc_metadata_array *request_metadata,
    grpc_byte_buffer **optional_payload,
    grpc_completion_queue *cq_bound_to_call,
    grpc_completion_queue *cq_for_notification, void *tag_new);

GRPCAPI grpc_server *grpc_server_create(const grpc_channel_args *args,
                                        void *reserved);

GRPCAPI void grpc_server_register_completion_queue(grpc_server *server,
                                                   grpc_completion_queue *cq,
                                                   void *reserved);

GRPCAPI void grpc_server_register_non_listening_completion_queue(
    grpc_server *server, grpc_completion_queue *q, void *reserved);

GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server *server,
                                                const char *addr);

GRPCAPI void grpc_server_start(grpc_server *server);

GRPCAPI void grpc_server_shutdown_and_notify(grpc_server *server,
                                             grpc_completion_queue *cq,
                                             void *tag);

GRPCAPI void grpc_server_cancel_all_calls(grpc_server *server);

GRPCAPI void grpc_server_destroy(grpc_server *server);

GRPCAPI int grpc_tracer_set_enabled(const char *name, int enabled);

GRPCAPI int grpc_header_key_is_legal(grpc_slice slice);

GRPCAPI int grpc_header_nonbin_value_is_legal(grpc_slice slice);

GRPCAPI int grpc_is_binary_header(grpc_slice slice);

GRPCAPI const char *grpc_call_error_to_string(grpc_call_error error);

GRPCAPI grpc_resource_quota *grpc_resource_quota_create(const char *trace_name);

GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota *resource_quota);

GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota *resource_quota);

GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota *resource_quota,
                                        size_t new_size);

GRPCAPI const grpc_arg_pointer_vtable *grpc_resource_quota_arg_vtable(void);

#ifdef __cplusplus
}
#endif

#endif /* GRPC_GRPC_H */