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>
#include <grpc/impl/codegen/connectivity_state.h>
#include <grpc/impl/codegen/propagation_bits.h>
#include <grpc/impl/codegen/grpc_types.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 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, const char *method,
    const char *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 census_context;

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

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

GRPCAPI char *grpc_channel_get_target(grpc_channel *channel);

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

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

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 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(const char *key, size_t length);

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

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

#ifdef __cplusplus
}
#endif

#endif /* GRPC_GRPC_H */