WordPress.org
Get WordPress

Make WordPress Core

Changeset 6637


Ignore:
Timestamp:
01/20/2008 06:53:42 AM (17 years ago)
Author:
ryan
Message:

phpdoc for pluggable.php from darkdragon. fixes #5509

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/pluggable.php

    r6600 r6637  
    2626
    2727if ( !function_exists('wp_set_current_user') ) :
     28/**
     29 * wp_set_current_user() - Changes the current user by ID or name
     30 *
     31 * Set $id to null and specify a name if you do not know a user's ID
     32 *
     33 * Some WordPress functionality is based on the current user and
     34 * not based on the signed in user. Therefore, it opens the ability
     35 * to edit and perform actions on users who aren't signed in.
     36 *
     37 * @since 2.0.4
     38 * @global object $current_user The current user object which holds the user data.
     39 * @uses do_action() Calls 'set_current_user' hook after setting the current user.
     40 *
     41 * @param int $id User ID
     42 * @param string $name User's username
     43 * @return WP_User Current user User object
     44 */
    2845function wp_set_current_user($id, $name = '') {
    2946    global $current_user;
    … …  
    4360
    4461if ( !function_exists('wp_get_current_user') ) :
     62/**
     63 * wp_get_current_user() - Retrieve the current user object
     64 *
     65 * @since 2.0.4
     66 *
     67 * @return WP_User Current user WP_User object
     68 */
    4569function wp_get_current_user() {
    4670    global $current_user;
    … …  
    5680 * get_currentuserinfo() - Populate global variables with information about the currently logged in user
    5781 *
    58  * {@internal Missing Long Description}}
     82 * Will set the current user, if the current user is not set. The current
     83 * user will be set to the logged in person. If no user is logged in, then
     84 * it will set the current user to 0, which is invalid and won't have any
     85 * permissions.
    5986 *
    6087 * @since 0.71
    61  *
    62  * @return unknown {@internal Missing Description}}
     88 * @uses $current_user Checks if the current user is set
     89 * @uses wp_validate_auth_cookie() Retrieves current logged in user.
     90 *
     91 * @return bool|null False on XMLRPC Request and invalid auth cookie. Null when current user set
    6392 */
    6493function get_currentuserinfo() {
    … …  
    82111if ( !function_exists('get_userdata') ) :
    83112/**
    84  * get_userdata() - Get an object containing data about a user
    85  *
    86  * {@internal Missing Long Description}}
     113 * get_userdata() - Retrieve user info by user ID
    87114 *
    88115 * @since 0.71
    89116 *
    90  * @param unknown_type $user_id {@internal Missing Description}}
    91  * @return unknown {@internal Missing Description}}
     117 * @param int $user_id User ID
     118 * @return bool|object False on failure, User DB row object
    92119 */
    93120function get_userdata( $user_id ) {
    … …  
    133160if ( !function_exists('get_userdatabylogin') ) :
    134161/**
    135  * get_userdatabylogin() - Grabs some info about a user based on their login name
    136  *
    137  * {@internal Missing Long Description}}
     162 * get_userdatabylogin() - Retrieve user info by login name
    138163 *
    139164 * @since 0.71
    140165 *
    141  * @param string $user_login {@internal Missing Description}}
    142  * @return unknown {@internal Missing Description}}
     166 * @param string $user_login User's username
     167 * @return bool|object False on failure, User DB row object
    143168 */
    144169function get_userdatabylogin($user_login) {
    … …  
    172197
    173198if ( !function_exists('get_user_by_email') ) :
     199/**
     200 * get_user_by_email() - Retrieve user info by email
     201 *
     202 * @since 2.5
     203 *
     204 * @param string $email User's email address
     205 * @return bool|object False on failure, User DB row object
     206 */
    174207function get_user_by_email($email) {
    175208    global $wpdb;
    … …  
    202235 * wp_mail() - Function to send mail, similar to PHP's mail
    203236 *
    204  * {@internal Missing Long Description}}
     237 * A true return value does not automatically mean that the
     238 * user received the email successfully. It just only means
     239 * that the method used was able to process the request
     240 * without any errors.
     241 *
     242 * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks
     243 * allow from creating a from address like 'Name <email@address.com>'
     244 * when both are set. If just 'wp_mail_from' is set, then just
     245 * the email address will be used with no name.
     246 *
     247 * The default content type is 'text/plain' which does not
     248 * allow using HTML. However, you can set the content type
     249 * of the email by using the 'wp_mail_content_type' filter.
     250 *
     251 * The default charset is based on the charset used on the
     252 * blog. The charset can be set using the 'wp_mail_charset'
     253 * filter.
    205254 *
    206255 * @since 1.2.1
    207  *
    208  * @param string $to {@internal Missing Description}}
    209  * @param string $subject {@internal Missing Description}}
    210  * @param string $message {@internal Missing Description}}
    211  * @param string $headers {@internal Missing Description}}
    212  * @return unknown {@internal Missing Description}}
     256 * @uses apply_filters() Calls 'wp_mail' hook on an array of all of the parameters.
     257 * @uses apply_filters() Calls 'wp_mail_from' hook to get the from email address.
     258 * @uses apply_filters() Calls 'wp_mail_from_name' hook to get the from address name.
     259 * @uses apply_filters() Calls 'wp_mail_content_type' hook to get the email content type.
     260 * @uses apply_filters() Calls 'wp_mail_charset' hook to get the email charset
     261 * @uses do_action_ref_array() Calls 'phpmailer_init' hook on the reference to
     262 *      phpmailer object.
     263 * @uses PHPMailer
     264 * @
     265 *
     266 * @param string $to Email address to send message
     267 * @param string $subject Email subject
     268 * @param string $message Message contents
     269 * @param string|array $headers Optional. Additional headers.
     270 * @return bool Whether the email contents were sent successfully.
    213271 */
    214272function wp_mail( $to, $subject, $message, $headers = '' ) {
    … …  
    360418 * wp_login() - Checks a users login information and logs them in if it checks out
    361419 *
    362  * {@internal Missing Long Description}}
     420 * Use the global $error to get the reason why the login failed.
     421 * If the username is blank, no error will be set, so assume
     422 * blank username on that case.
     423 *
     424 * Plugins extending this function should also provide the global
     425 * $error and set what the error is, so that those checking the
     426 * global for why there was a failure can utilize it later.
    363427 *
    364428 * @since 1.2.2
    365  *
    366  * @param string $username {@internal Missing Description}}
    367  * @param string $password {@internal Missing Description}}
    368  * @param bool $deprecated {@internal Missing Description}}
    369  * @return unknown {@internal Missing Description}}
     429 * @global string $error Error when false is returned
     430 *
     431 * @param string $username User's username
     432 * @param string $password User's password
     433 * @param bool $deprecated Not used
     434 * @return bool False on login failure, true on successful check
    370435 */
    371436function wp_login($username, $password, $deprecated = '') {
    … …  
    403468
    404469if ( !function_exists('wp_validate_auth_cookie') ) :
     470/**
     471 * wp_validate_auth_cookie() - Validates authentication cookie
     472 *
     473 * The checks include making sure that the authentication cookie
     474 * is set and pulling in the contents (if $cookie is not used).
     475 *
     476 * Makes sure the cookie is not expired. Verifies the hash in
     477 * cookie is what is should be and compares the two.
     478 *
     479 * @since 2.5
     480 *
     481 * @param string $cookie Optional. If used, will validate contents instead of cookie's
     482 * @return bool|int False if invalid cookie, User ID if valid.
     483 */
    405484function wp_validate_auth_cookie($cookie = '') {
    406485    if ( empty($cookie) ) {
    … …  
    436515
    437516if ( !function_exists('wp_generate_auth_cookie') ) :
     517/**
     518 * wp_generate_auth_cookie() - Generate authentication cookie contents
     519 *
     520 * @since 2.5
     521 * @uses apply_filters() Calls 'auth_cookie' hook on $cookie contents, User ID
     522 *      and expiration of cookie.
     523 *
     524 * @param int $user_id User ID
     525 * @param int $expiration Cookie expiration in seconds
     526 * @return string Authentication cookie contents
     527 */
    438528function wp_generate_auth_cookie($user_id, $expiration) {
    439529    $user = get_userdata($user_id);
    … …  
    449539
    450540if ( !function_exists('wp_set_auth_cookie') ) :
     541/**
     542 * wp_set_auth_cookie() - Sets the authentication cookies based User ID
     543 *
     544 * The $remember parameter increases the time that the cookie will
     545 * be kept. The default the cookie is kept without remembering is
     546 * two days. When $remember is set, the cookies will be kept for
     547 * 14 days or two weeks.
     548 *
     549 * @since 2.5
     550 *
     551 * @param int $user_id User ID
     552 * @param bool $remember Whether to remember the user or not
     553 */
    451554function wp_set_auth_cookie($user_id, $remember = false) {
    452555    if ( $remember ) {
    … …  
    468571
    469572if ( !function_exists('wp_clear_auth_cookie') ) :
     573/**
     574 * wp_clear_auth_cookie() - Deletes all of the cookies associated with authentication
     575 *
     576 * @since 2.5
     577 */
    470578function wp_clear_auth_cookie() {
    471579    setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN);
    … …  
    484592 * is_user_logged_in() - Checks if the current visitor is a logged in user
    485593 *
    486  * {@internal Missing Long Description}}
    487  *
    488594 * @since 2.0.0
    489595 *
    490  * @return bool {@internal Missing Description}}
     596 * @return bool True if user is logged in, false if not logged in.
    491597 */
    492598function is_user_logged_in() {
    … …  
    503609/**
    504610 * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page
    505  *
    506  * {@internal Missing Long Description}}
    507611 *
    508612 * @since 1.5
    … …  
    512616    if ( (!empty($_COOKIE[AUTH_COOKIE]) &&
    513617                !wp_validate_auth_cookie($_COOKIE[AUTH_COOKIE])) ||
    514              (empty($_COOKIE[AUTH_COOKIE])) ) {
     618            (empty($_COOKIE[AUTH_COOKIE])) ) {
    515619        nocache_headers();
    516620
    … …  
    525629 * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits
    526630 *
    527  * {@internal Missing Long Description}}
    528  *
    529631 * @since 1.2.0
    530  *
    531  * @param unknown_type $action {@internal Missing Description}}
     632 * @uses do_action() Calls 'check_admin_referer' on $action.
     633 *
     634 * @param string $action Action nonce
    532635 */
    533636function check_admin_referer($action = -1) {
    … …  
    543646
    544647if ( !function_exists('check_ajax_referer') ) :
     648/**
     649 * check_ajax_referer() - Verifies the AJAX request to prevent processing requests external of the blog.
     650 *
     651 * @since 2.0.4
     652 *
     653 * @param string $action Action nonce
     654 */
    545655function check_ajax_referer( $action = -1 ) {
    546656    $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce'];
    … …  
    564674        if ( ! $user_id = wp_validate_auth_cookie( $auth_cookie ) )
    565675            die('-1');
    566    
     676
    567677        if ( $current_id != $user_id )
    568678            die('-1');
    … …  
    578688 * @link http://support.microsoft.com/kb/q176113/
    579689 * @since 1.5.1
    580  *
    581  * @param string $location {@internal Missing Description}}
    582  * @param int $status {@internal Missing Description}}
    583  * @return unknown {@internal Missing Description}}
     690 * @uses apply_filters() Calls 'wp_redirect' hook on $location and $status.
     691 *
     692 * @param string $location The path to redirect to
     693 * @param int $status Status code to use
     694 * @return bool False if $location is not set
    584695 */
    585696function wp_redirect($location, $status = 302) {
    … …  
    635746 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect()
    636747 *
     748 * Checks whether the $location is using an allowed host, if it has an absolute
     749 * path. A plugin can therefore set or remove allowed host(s) to or from the list.
     750 *
     751 * If the host is not allowed, then the redirect is to wp-admin on the siteurl
     752 * instead. This prevents malicious redirects which redirect to another host, but
     753 * only used in a few places.
     754 *
    637755 * @since 2.3
     756 * @uses apply_filters() Calls 'allowed_redirect_hosts' on an array containing
     757 *      WordPress host string and $location host string.
    638758 *
    639759 * @return void Does not return anything
    … …  
    664784 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts
    665785 *
    666  * @since 1.0
     786 * @since 1.0.0
    667787 *
    668788 * @param int $comment_id Comment ID
Note: See TracChangeset for help on using the changeset viewer.