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 <stddef.h>
#include <grpc/byte_buffer.h>
#include <grpc/support/slice.h>
#include <grpc/support/time.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct grpc_completion_queue grpc_completion_queue;

typedef struct grpc_alarm grpc_alarm;

typedef struct grpc_channel grpc_channel;

typedef struct grpc_server grpc_server;

typedef struct grpc_call grpc_call;

typedef enum {
  GRPC_ARG_STRING,
  GRPC_ARG_INTEGER,
  GRPC_ARG_POINTER
} grpc_arg_type;

typedef struct {
  grpc_arg_type type;
  char *key;
  union {
    char *string;
    int integer;
    struct {
      void *p;
      void *(*copy)(void *p);
      void (*destroy)(void *p);
    } pointer;
  } value;
} grpc_arg;

typedef struct {
  size_t num_args;
  grpc_arg *args;
} grpc_channel_args;

/* Channel argument keys: */
#define GRPC_ARG_ENABLE_CENSUS "grpc.census"

#define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams"

#define GRPC_ARG_MAX_MESSAGE_LENGTH "grpc.max_message_length"

#define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \
  "grpc.http2.initial_sequence_number"

#define GRPC_ARG_HTTP2_STREAM_LOOKAHEAD_BYTES "grpc.http2.lookahead_bytes"

#define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_DECODER \
  "grpc.http2.hpack_table_size.decoder"

#define GRPC_ARG_HTTP2_HPACK_TABLE_SIZE_ENCODER \
  "grpc.http2.hpack_table_size.encoder"

#define GRPC_ARG_DEFAULT_AUTHORITY "grpc.default_authority"

#define GRPC_ARG_PRIMARY_USER_AGENT_STRING "grpc.primary_user_agent"

#define GRPC_ARG_SECONDARY_USER_AGENT_STRING "grpc.secondary_user_agent"
/* The caller of the secure_channel_create functions may override the target
   name used for SSL host name checking using this channel argument which is of
   type GRPC_ARG_STRING. This *should* be used for testing only.
   If this argument is not specified, the name used for SSL host name checking
   will be the target parameter (assuming that the secure channel is an SSL
   channel). If this parameter is specified and the underlying is not an SSL
   channel, it will just be ignored. */
#define GRPC_SSL_TARGET_NAME_OVERRIDE_ARG "grpc.ssl_target_name_override"

typedef enum {
  GRPC_CHANNEL_IDLE,
  GRPC_CHANNEL_CONNECTING,
  GRPC_CHANNEL_READY,
  GRPC_CHANNEL_TRANSIENT_FAILURE,
  GRPC_CHANNEL_FATAL_FAILURE
} grpc_connectivity_state;

typedef enum grpc_call_error {
  GRPC_CALL_OK = 0,
  GRPC_CALL_ERROR,
  GRPC_CALL_ERROR_NOT_ON_SERVER,
  GRPC_CALL_ERROR_NOT_ON_CLIENT,
  GRPC_CALL_ERROR_ALREADY_ACCEPTED,
  GRPC_CALL_ERROR_ALREADY_INVOKED,
  GRPC_CALL_ERROR_NOT_INVOKED,
  GRPC_CALL_ERROR_ALREADY_FINISHED,
  GRPC_CALL_ERROR_TOO_MANY_OPERATIONS,
  GRPC_CALL_ERROR_INVALID_FLAGS,
  GRPC_CALL_ERROR_INVALID_METADATA,
  GRPC_CALL_ERROR_INVALID_MESSAGE,
  GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE,
  GRPC_CALL_ERROR_BATCH_TOO_BIG
} grpc_call_error;

/* Write Flags: */
#define GRPC_WRITE_BUFFER_HINT (0x00000001u)

#define GRPC_WRITE_NO_COMPRESS (0x00000002u)

#define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS)

typedef struct grpc_metadata {
  const char *key;
  const char *value;
  size_t value_length;
  gpr_uint32 flags;

  struct {
    void *obfuscated[4];
  } internal_data;
} grpc_metadata;

typedef enum grpc_completion_type {
  GRPC_QUEUE_SHUTDOWN,
  GRPC_QUEUE_TIMEOUT,
  GRPC_OP_COMPLETE
} grpc_completion_type;

typedef struct grpc_event {
  grpc_completion_type type;
  int success;
  void *tag;
} grpc_event;

typedef struct {
  size_t count;
  size_t capacity;
  grpc_metadata *metadata;
} grpc_metadata_array;

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

typedef struct {
  char *method;
  size_t method_capacity;
  char *host;
  size_t host_capacity;
  gpr_timespec deadline;
  void *reserved;
} grpc_call_details;

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

typedef enum {
  GRPC_OP_SEND_INITIAL_METADATA = 0,
  GRPC_OP_SEND_MESSAGE,
  GRPC_OP_SEND_CLOSE_FROM_CLIENT,
  GRPC_OP_SEND_STATUS_FROM_SERVER,
  GRPC_OP_RECV_INITIAL_METADATA,
  GRPC_OP_RECV_MESSAGE,
  GRPC_OP_RECV_STATUS_ON_CLIENT,
  GRPC_OP_RECV_CLOSE_ON_SERVER
} grpc_op_type;

typedef struct grpc_op {
  grpc_op_type op;
  gpr_uint32 flags;
  void *reserved;
  union {
    struct {
      void *reserved[8];
    } reserved;
    struct {
      size_t count;
      grpc_metadata *metadata;
    } send_initial_metadata;
    grpc_byte_buffer *send_message;
    struct {
      size_t trailing_metadata_count;
      grpc_metadata *trailing_metadata;
      grpc_status_code status;
      const char *status_details;
    } send_status_from_server;
    grpc_metadata_array *recv_initial_metadata;
    grpc_byte_buffer **recv_message;
    struct {
      grpc_metadata_array *trailing_metadata;
      grpc_status_code *status;
      char **status_details;
      size_t *status_details_capacity;
    } recv_status_on_client;
    struct {
      int *cancelled;
    } recv_close_on_server;
  } data;
} grpc_op;

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

/* Propagation bits: this can be bitwise or-ed to form propagation_mask for
 * grpc_call */
#define GRPC_PROPAGATE_DEADLINE ((gpr_uint32)1)

#define GRPC_PROPAGATE_CENSUS_STATS_CONTEXT ((gpr_uint32)2)
#define GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT ((gpr_uint32)4)

#define GRPC_PROPAGATE_CANCELLATION ((gpr_uint32)8)

/* Default propagation mask: clients of the core API are encouraged to encode
   deltas from this in their implementations... ie write:
   GRPC_PROPAGATE_DEFAULTS & ~GRPC_PROPAGATE_DEADLINE to disable deadline
   propagation. Doing so gives flexibility in the future to define new
   propagation types that are default inherited or not. */
#define GRPC_PROPAGATE_DEFAULTS                                                \
  ((gpr_uint32)((                                                              \
      0xffff | GRPC_PROPAGATE_DEADLINE | GRPC_PROPAGATE_CENSUS_STATS_CONTEXT | \
      GRPC_PROPAGATE_CENSUS_TRACING_CONTEXT | GRPC_PROPAGATE_CANCELLATION)))

void grpc_init(void);

void grpc_shutdown(void);

const char *grpc_version_string(void);

grpc_completion_queue *grpc_completion_queue_create(void *reserved);

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

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

#define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6

void grpc_completion_queue_shutdown(grpc_completion_queue *cq);

void grpc_completion_queue_destroy(grpc_completion_queue *cq);

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

void grpc_alarm_cancel(grpc_alarm *alarm);

void grpc_alarm_destroy(grpc_alarm *alarm);

grpc_connectivity_state grpc_channel_check_connectivity_state(
    grpc_channel *channel, int try_to_connect);

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

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

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

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

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

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

char *grpc_call_get_peer(grpc_call *call);

struct census_context;

/* Set census context for a call; Must be called before first call to
   grpc_call_start_batch(). */
void grpc_census_call_set_context(grpc_call *call,
                                  struct census_context *context);

/* Retrieve the calls current census context. */
struct census_context *grpc_census_call_get_context(grpc_call *call);

char *grpc_channel_get_target(grpc_channel *channel);

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

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

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

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

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

void grpc_call_destroy(grpc_call *call);

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);

void *grpc_server_register_method(grpc_server *server, const char *method,
                                  const char *host);

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);

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

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

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

void grpc_server_start(grpc_server *server);

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

void grpc_server_cancel_all_calls(grpc_server *server);

void grpc_server_destroy(grpc_server *server);

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

int grpc_header_key_is_legal(const char *key, size_t length);

int grpc_header_nonbin_value_is_legal(const char *value, size_t length);

int grpc_is_binary_header(const char *key, size_t length);

#ifdef __cplusplus
}
#endif

#endif /* GRPC_GRPC_H */