ks_bquery.h File Reference

Interface to libkarmaclient's bquery protocol. More...

#include "ks_array.h"
#include "ks_number.h"
#include "ks_string.h"

Go to the source code of this file.

Data Structures
struct	_ks_bquery_t
	Representation of libkarmaclient's bquery packet. More...
Defines
#define	KS_IDT_IP4   0
#define	KS_IDT_IP4_ADDRESS   0
#define	KS_IDT_IP6   1
#define	KS_IDT_IP6_ADDRESS   1
#define	KS_IDT_DOMAIN   2
#define	KS_IDT_DOMAIN_NAME   2
#define	KS_IDT_EMAIL   3
#define	KS_IDT_EMAIL_ADDRESS   3
#define	KS_IDT_URL   4
#define	KS_IDT_URI   4
#define	KS_FL_FACTS   1
#define	KS_COMBINER_DEFAULT   "default"
#define	KS_QUERY_HOST_DEFAULT   "query.karmasphere.com"
#define	KS_SLAVE_HOST_DEFAULT   "query.karmasphere.com"
#define	KS_QUERY_PORT_DEFAULT   "8666"
#define	KS_SLAVE_PORT_DEFAULT   "8666"
#define	KS_TAG_SMTP_CLIENT_IP   "smtp.client-ip"
#define	KS_TAG_SMTP_ENV_HELO   "smtp.env.helo"
#define	KS_TAG_SMTP_ENV_MAIL_FROM   "smtp.env.mail-from"
#define	KS_TAG_SMTP_ENV_RCPT_TO   "smtp.env.rcpt-to"
#define	KS_TAG_SMTP_HEADER_FROM_ADDRESS   "smtp.header.from.address"
Typedefs
typedef _ks_bquery_t	ks_bquery_t
	Representation of libkarmaclient's bquery packet.
Functions
ks_type_t *	ks_bquery_type (void)
ks_bquery_t *	ks_bquery_new (void)
void	ks_bquery_free (ks_bquery_t *)
void	ks_bquery_feed_add (ks_bquery_t *, const char *)
void	ks_bquery_composite_add (ks_bquery_t *, const char *)
void	ks_bquery_combiner_add (ks_bquery_t *, const char *)
void	ks_bquery_identity_add (ks_bquery_t *, const char *, int)
void	ks_bquery_identity_add_tagged (ks_bquery_t *, const char *, int, const char *)
void	ks_bquery_id_set (ks_bquery_t *, const char *, size_t)
ks_string_t *	ks_bquery_id_get (ks_bquery_t *)
void	ks_bquery_flags_set (ks_bquery_t *, long)
int	ks_bquery_has_auth (ks_bquery_t *)
void	ks_bquery_set_auth (ks_bquery_t *, const char *, const char *)
ks_string_t *	ks_bquery_packet (ks_bquery_t *)

---

Detailed Description

Interface to libkarmaclient's bquery protocol.

Declarations of types and functions defined in ks_bquery.c. Do not include this file directly in your client. Instead, include the application header file ks.h, which will include all the libkarmaclient headers for you.

Definition in file ks_bquery.h.

---

Define Documentation

#define KS_COMBINER_DEFAULT   "default"

Definition at line 78 of file ks_bquery.h.

#define KS_FL_FACTS   1

Definition at line 76 of file ks_bquery.h. Referenced by main().

#define KS_IDT_DOMAIN   2

Domain name identity type. This is one of the possible values for the 3rd argument of ks_bquery_identity_add or ks_bquery_identity_add_tagged. Definition at line 54 of file ks_bquery.h. Referenced by main().

#define KS_IDT_DOMAIN_NAME   2

Definition at line 55 of file ks_bquery.h.

#define KS_IDT_EMAIL   3

Email address identity type. This will also allow reputation checks against the hostname or domain of the given email address. Definition at line 63 of file ks_bquery.h. Referenced by main().

#define KS_IDT_EMAIL_ADDRESS   3

Definition at line 64 of file ks_bquery.h.

#define KS_IDT_IP4   0

IPv4 address identity type. This is one of the possible values for the 3rd argument of ks_bquery_identity_add or ks_bquery_identity_add_tagged. Definition at line 36 of file ks_bquery.h. Referenced by main().

#define KS_IDT_IP4_ADDRESS   0

Definition at line 37 of file ks_bquery.h. Referenced by main().

#define KS_IDT_IP6   1

IPv6 address identity type. This is one of the possible values for the 3rd argument of ks_bquery_identity_add or ks_bquery_identity_add_tagged. Definition at line 45 of file ks_bquery.h. Referenced by main().

#define KS_IDT_IP6_ADDRESS   1

Definition at line 46 of file ks_bquery.h.

#define KS_IDT_URI   4

Definition at line 72 of file ks_bquery.h.

#define KS_IDT_URL   4

URL identity type. This will also allow reputation checks against the domain hosting the URL. Definition at line 71 of file ks_bquery.h. Referenced by main().

#define KS_QUERY_HOST_DEFAULT   "query.karmasphere.com"

The hostname of the default query server. Definition at line 82 of file ks_bquery.h. Referenced by main().

#define KS_QUERY_PORT_DEFAULT   "8666"

The port number of the default query server. Definition at line 85 of file ks_bquery.h. Referenced by main().

#define KS_SLAVE_HOST_DEFAULT   "query.karmasphere.com"

Definition at line 83 of file ks_bquery.h. Referenced by ks_socket_new().

#define KS_SLAVE_PORT_DEFAULT   "8666"

Definition at line 86 of file ks_bquery.h. Referenced by ks_socket_new().

#define KS_TAG_SMTP_CLIENT_IP   "smtp.client-ip"

A tag which distinguishes the SMTP client IP from other IPs in a query. This tag is usually a singleton. Definition at line 91 of file ks_bquery.h.

#define KS_TAG_SMTP_ENV_HELO   "smtp.env.helo"

A tag which distinguishes the SMTP HELO domain from other domains in a query. This tag is usually a singleton. Definition at line 94 of file ks_bquery.h.

#define KS_TAG_SMTP_ENV_MAIL_FROM   "smtp.env.mail-from"

A tag which distinguishes the SMTP MAIL-FROM address from other email addresses in a query. This tag is usually a singleton. Definition at line 97 of file ks_bquery.h.

#define KS_TAG_SMTP_ENV_RCPT_TO   "smtp.env.rcpt-to"

A tag which distinguishes an SMTP RCPT-TO address from other email addresses in a query. Definition at line 100 of file ks_bquery.h.

#define KS_TAG_SMTP_HEADER_FROM_ADDRESS   "smtp.header.from.address"

A tag which distinguishes a header From: address from other email addresses in a query. This tag is usually a singleton. Definition at line 103 of file ks_bquery.h.

---

Typedef Documentation

typedef struct _ks_bquery_t ks_bquery_t

Representation of libkarmaclient's bquery packet.

---

Function Documentation

void ks_bquery_combiner_add (  ks_bquery_t *  q, const char *  id )

Add an additional combiner ito be queried to a ks_bquery_t. Parameters: q  a pointer to the ks_bquery_t to which the combiner is to be added id  the combiner's name (a NUL terminated string) Returns: nothing Definition at line 260 of file ks_bquery.c. References _ks_bquery_t::combiners, ks_array_add(), and ks_string_new().

void ks_bquery_composite_add (  ks_bquery_t *  q, const char *  id )

Add a composite (aka feedset) to be queried to a ks_bquery_packet. Parameters: q  a pointer to the ks_bquery_t to which the composite should be added id  the name of the composite to be queried (a NUL terminated string) Returns: nothing Definition at line 245 of file ks_bquery.c. References _ks_bquery_t::composites, ks_array_add(), and ks_string_new(). Referenced by main().

void ks_bquery_feed_add (  ks_bquery_t *  q, const char *  id )

Adds a feed to be queried to a ks_bquery_t. Parameters: q  a pointer to the ks_bquery_t the feed is to be added to id  the number of the id to be queried Returns: nothing Definition at line 229 of file ks_bquery.c. References _ks_bquery_t::feeds, ks_array_add(), and ks_string_new(). Referenced by main().

void ks_bquery_flags_set (  ks_bquery_t *  q, long  flags )

Set the flags in a ks_bquery_t. Parameters: q  a pointer to the ks_bquery_t whose flags are to be set flags  the flags to be set XOR'd together. Valid flags are: KS_FL_FACTS Returns: nothing Definition at line 355 of file ks_bquery.c. References _ks_bquery_t::flags, and ks_number_set(). Referenced by main().

void ks_bquery_free (  ks_bquery_t *  q  )

Destroys a ks_bquery_t, freeing all memory that has been allocated for it. Parameters: q  a pointer to the ks_bquery_t to be destroyed Returns: nothing Definition at line 159 of file ks_bquery.c. References _ks_bquery_t::combiners, _ks_bquery_t::composites, _ks_bquery_t::credentials, _ks_bquery_t::feeds, _ks_bquery_t::flags, _ks_bquery_t::id, _ks_bquery_t::identities, ks_array_fini(), ks_free(), ks_number_fini(), ks_string_free(), and _ks_bquery_t::principal. Referenced by main().

int ks_bquery_has_auth (  ks_bquery_t *  q  )

Determine whether or not a ks_bquery_t has authentication tokens. Parameters: q  a pointer to the ks_bquery_t being inspected Returns: zero if the given ks_bquery_t does not have authentication tokens, or nonzero otherwise. Definition at line 386 of file ks_bquery.c. References _ks_bquery_t::principal. Referenced by ks_socket_send().

ks_string_t* ks_bquery_id_get (  ks_bquery_t *  q  )

Returns the cookie value from a ks_bquery_t. If the ks_bquery_t does not already have an ID, one is generated and stored within it. libkarmaclient does not generate bquery packets that do not have cookies. Parameters: q  a pointer to the ks_bquery_t whose id is to be inspected Returns: a pointer to the ks_bquery_t's cookie on success, or NULL on failure Definition at line 210 of file ks_bquery.c. References _ks_bquery_t::id, and ks_string_new(). Referenced by ks_socket_ask().

void ks_bquery_id_set (  ks_bquery_t *  q, const char *  id, size_t  len )

Sets the value of the cookie for this query. This will be returned by the karmaserver in the response packet to allow the client to keep track of query/response pairs. Parameters: q  a pointer to the ks_bquery_t whose id is to be set id  a string to uniquely identify this ks_bquery_t and its associated ks_response_t len  the length of the id string (in chars) Returns: nothing Definition at line 189 of file ks_bquery.c. References _ks_bquery_t::id, ks_string_new(), and ks_string_set().

void ks_bquery_identity_add (  ks_bquery_t *  q, const char *  id, int  idt )

Add an identity (on which an opinion is sought from a karmaserver) to a ks_bquery_t. To pass additional context information about the identity, use ks_bquery_identity_add_tagged. Parameters: q  a pointer to the ks_bquery_t to which the identity should be added. id  the identity to add to the ks_bquery_t (a NUL terminated string) idt  an integer describing the type of the identity. Valid values for types are: KS_IDT_IP4_ADDRESS KS_IDT_IP6_ADDRESS KS_IDT_DOMAIN_NAME KS_IDT_EMAIL_ADDRESS KS_IDT_URI Returns: nothing Definition at line 314 of file ks_bquery.c.

void ks_bquery_identity_add_tagged (  ks_bquery_t *  q, const char *  id, int  idt, const char *  tag )

Add an identity (on which an opinion is sought from a karmaserver) and a tag string to a ks_bquery_t. Parameters: q  a pointer to the ks_bquery_t to which the identity should be added. id  the identity to add to the ks_bquery_t (a NUL terminated string) idt  an integer describing the type of the identity. Valid values for types are: KS_IDT_IP4_ADDRESS KS_IDT_IP6_ADDRESS KS_IDT_DOMAIN_NAME KS_IDT_EMAIL_ADDRESS KS_IDT_URI tag  a NUL terminated string to be used as a tag Returns: nothing Definition at line 338 of file ks_bquery.c. References ks_array_add(), and ks_string_new().

ks_bquery_t* ks_bquery_new (  void   )

Constructs a new ks_bquery_t. This function allocates memory that must be freed by ks_bquery_free(). Returns: a pointer to the newly created ks_bquery_t on success, or NULL on failure. Definition at line 135 of file ks_bquery.c. References _ks_bquery_t::base, _ks_bquery_t::combiners, _ks_bquery_t::composites, _ks_bquery_t::credentials, _ks_bquery_t::feeds, _ks_bquery_t::flags, _ks_bquery_t::id, _ks_bquery_t::identities, ks_array_init(), ks_malloc(), ks_number_init(), _ks_bquery_t::principal, and _ks_base_t::type. Referenced by main().

ks_string_t* ks_bquery_packet (  ks_bquery_t *  q  )

Convert a ks_bquery_t object into a bquery packet. Parameters: q  a pointer to the ks_bquery_t to be converted Returns: a pointer to a ks_string_t containing the bquery packet. The memory used for this ks_string_t can be reclaimed by destroying the ks_string_t with ks_string_free(). Definition at line 370 of file ks_bquery.c. References ks_string_new(). Referenced by ks_socket_send().

void ks_bquery_set_auth (  ks_bquery_t *  q, const char *  p, const char *  c )

Set authentication tokens for a bquery object. Parameters: q  a pointer to the ks_bquery_t to be authenticated p  a NUL terminated string containing an identifier used to authenticate client connections. This may be a login or account name. The precise details will depend on the policy of the query server being used. c  a NUL terminated string containing the credentials used to authenticate the principal, p. this may be a password, or a certificate. The precise details may depend on the policy of the query server being used. Returns: nothing. Definition at line 407 of file ks_bquery.c. References _ks_bquery_t::credentials, ks_string_free(), ks_string_new(), ks_string_set(), and _ks_bquery_t::principal. Referenced by ks_socket_send().

ks_type_t* ks_bquery_type (  void   )

Returns the metaclass for ks_bquery_t objects. Returns: a pointer to the ks_bquery_t metaclass, ks_type_bquery Definition at line 120 of file ks_bquery.c.

---